BlueDesk — System Architecture

sequenceDiagram
    autonumber
    actor User
    participant FE as Next.js Frontend
(Port 3000)
    participant BE as Go Backend
(Port 8080)
    participant MS as Microsoft Entra ID
    participant DB as PostgreSQL

    User->>FE: Click "Sign In with Microsoft"
    FE->>BE: GET /api/v1/auth/login
    BE->>BE: Generate CSRF state + oauth_state cookie
    BE-->>FE: auth_url + Set-Cookie: oauth_state
    FE->>MS: Redirect to auth_url
    User->>MS: Enter credentials (+ 2FA)
    MS->>BE: GET /api/v1/auth/callback?code=...&state=...
    BE->>BE: Validate CSRF (cookie vs query param)
    BE->>MS: Exchange auth code for access token
    MS-->>BE: Access token + user info
    BE->>DB: Find or create user record
    DB-->>BE: User data
    BE->>FE: Set-Cookie: session_token, refresh_token, user_info
    FE->>BE: GET /api/v1/user/me (verify role)

    alt IT Admin
        FE->>User: Show Admin Dashboard
    else Regular / App Admin
        FE->>User: Show App Launcher
    end

    Note over User,DB: First-time users are auto-created with no app access.
IT admin must assign applications.
        

sequenceDiagram
    autonumber
    actor User
    participant FE as Next.js Frontend
    participant BE as Go Backend
    participant DB as PostgreSQL
    participant App as Target Application

    User->>FE: Click app tile in launcher
    FE->>BE: POST /api/v1/launcher/apps/{id}
    BE->>DB: Check user_app_permissions
    DB-->>BE: Permission record (role, can_view, can_edit, ...)

    alt No permission found
        BE-->>FE: 403 Forbidden
        FE-->>User: "Access denied" message
    else Has permission
        BE->>BE: Generate launch JWT with
user identity + app permissions
        BE-->>FE: Launch JWT + app URL
        FE->>App: Redirect with JWT
        App->>App: Validate JWT signature
        App-->>User: Auto-logged in, permissions applied
    end

    Note over BE,App: The launch JWT is distinct from the session JWT.
It is scoped to a single application.