Document the authentication sequence

[mikenikles]

sequenceDiagram
    autonumber

    participant /
    participant /dashboard
    participant /login
    participant /login/github
    participant githubAuthorize as github.com/login/oauth/authorize
    participant /login/github/callback
    participant githubAccessToken as github.com/login/oauth/access_token
    participant githubUser as api.github.com/user
    participant PostgreSQL

    link /: Source @ https://github.com/WebstoneHQ/platform/blob/main/services/website/src/routes/index.svelte
    link /dashboard: Source @ https://github.com/WebstoneHQ/platform/blob/main/services/website/src/routes/dashboard.svelte
    link /login: Source @ https://github.com/WebstoneHQ/platform/blob/main/services/website/src/routes/login/index.svelte
    link /login/github: Source @ https://github.com/WebstoneHQ/platform/blob/main/services/website/src/routes/login/github/index.ts
    link /login/github/callback: Source @ https://github.com/WebstoneHQ/platform/blob/main/services/website/src/routes/login/github/callback.ts

    /-->>/dashboard: Redirect if authenticated
    /->>/login: Redirect if not authenticated
    Note over /login: User selects "Continue with GitHub"
    /login->>/login/github: Redirect
    /login/github->>githubAuthorize: Redirect, with `client_id`<br>query parameter attached
    Note over githubAuthorize: Display OAuth prompt to user.
    githubAuthorize->>/login/github/callback: GET request with `code`<br>query parameter attached
    /login/github/callback->>githubAccessToken: POST request to<br>retrieve an access token
    githubAccessToken->>/login/github/callback: Return an access token
    /login/github/callback->>githubUser: GET request to fetch user info with the access token
    githubUser->>/login/github/callback: Return user information
    Note over /login/github/callback: Use `id`, `email`,<br>`login`, and `name`
    /login/github/callback->>PostgreSQL: Persist the user information
    Note over /login/github/callback: Sign JWT and serialize<br>the `jwt` cookie with the<br>user information
    /login/github/callback->>/dashboard: Redirect