Auth service responsible for authentication of users.

In v1 it is basic auth with login/password → JWT authentication.

Passwords are stored in DB as hashes.

JWT: see ADR 001.

Component Diagram

C4Component
    title Component Diagram for Auth Service

    Container_Boundary(auth, "Auth Service") {
        Component(handlers, "Handlers", "Go", "HTTP layer: parse requests, return responses")
        Component(authService, "Auth Service", "Go", "Business logic: validate credentials, generate tokens")
        Component(userRepo, "User Repository", "Go", "Data access for users table")
        Component(tokenRepo, "Token Repository", "Go", "Data access for refresh_tokens table")
        Component(hasher, "Password Hasher", "bcrypt", "Hash and verify passwords")
        Component(jwtManager, "JWT Manager", "golang-jwt", "Generate and validate JWT tokens")
    }

    Container_Ext(spa, "SPA", "React", "Frontend application")
    Container_Ext(taskService, "Task Service", "Go", "gRPC client for token validation")
    ContainerDb_Ext(db, "Auth Database", "PostgreSQL", "Stores users and refresh tokens")

    Rel(spa, handlers, "REST API", "HTTP/JSON")
    Rel(taskService, handlers, "Validate token", "gRPC")
    Rel(handlers, authService, "Uses")
    Rel(authService, userRepo, "Uses")
    Rel(authService, tokenRepo, "Uses")
    Rel(authService, hasher, "Uses")
    Rel(authService, jwtManager, "Uses")
    Rel(userRepo, db, "Reads/Writes", "SQL")
    Rel(tokenRepo, db, "Reads/Writes", "SQL")

ER Diagram

plannerauthdb - public.png

Use cases

  1. Registration — add new users to DB, create access and refresh tokens
  2. Log in — verify credentials, return access/refresh tokens
  3. Refresh — create new refresh token, delete the old one
  4. Log out — revoke refresh token and delete both tokens on client side

See each use case in details.

UC1 Registration

Actions table

User action System actions Alternative scenarios
User enters login and password 1. Auth Service: Validate input 1a. Validation failed → show error
2. Auth Service: Check if login already exist 2a. Login exists → show error
3. Auth Service: Hash password
4. Auth Service: Create user in db 4a. DB error → log db error, show generic error
5. Auth Service: Create access and refresh tokens
6. Auth Service: Save refresh token to DB
7. Auth Service: Return access and refresh tokens.
SPA: Redirect user to main tasks view.

Sequence diagram

sequenceDiagram
    actor User
    participant SPA
    participant Auth as Auth Service
    participant DB as Auth DB

    User->>SPA: 1. Enter login and password
    SPA->>Auth: 2. POST /register {login, password}
    
    Auth->>Auth: 3. Validate input
    
    alt Invalid input
        Auth-->>SPA: 2a. Return error
        SPA-->>User: 1a. Show validation error
    else Valid input
        Auth->>DB: 4. Check if login exists
        
        alt Login taken
            DB-->>Auth: 4a. User found
            Auth-->>SPA: 2b. Return error
            SPA-->>User: 1b. Show error "login already taken"
        else Login available
            DB-->>Auth: 4b. User not found
            Auth->>Auth: 5. Hash password
            Auth->>DB: 6. Insert new user
            DB-->>Auth: 6a. Ok/error
            Auth->>Auth: 7. Generate access + refresh tokens
            Auth->>DB: 8. Save refresh token
            DB-->>Auth: 8a. Ok/error
            Auth-->>SPA: 2c. Success {accessToken, refreshToken}
            SPA->>SPA: 10. Save tokens
            SPA-->>User: 1c. Redirect to tasks view
        end
    end