# Architecture

This reference app follows a standard server-side OAuth flow suited for a backend (Node.js/Express) application.

## Components

1.  **Express Server (`src/index.ts`)**
    -   Host web endpoints (`/`, `/login`, `/oauth/callback`).
    -   Manages the browser session (cookie-based) using `iron-session`.
    -   NOTE: The browser session is *separate* from the OAuth session. The browser session just remembers "Who is logged in here?" (by storing the DID).

2.  **OAuth Client (`src/client.ts`)**
    -   Instance of `NodeOAuthClient`.
    -   Manages the complexity of the handshake, token exchanges, and key management (DPoP).
    -   Uses `client-metadata` to define itself to the world (redirect URIs, etc.).

3.  **Storage Adapters (`src/storage.ts`)**
    -   **State Store**: Temporarily stores the random `state` parameter generated during the login request to prevent CSRF.
    -   **Session Store**: Persists the actual Access and Refresh tokens (the "OAuth Session") mapped to the user's DID.

4.  **Database (`src/db.ts`)**
    -   A simple SQLite database to back the Storage Adapters.
    -   In a real app, this would be Postgres, Redis, etc.

## The Flow

1.  **Initiation**:
    -   User enters Handle.
    -   App calls `client.authorize(handle)`.
    -   App redirects User to the PDS (e.g., bsky.social login page).
2.  **Authentication**:
    -   User logs in at the PDS.
    -   User approves the app.
3.  **Callback**:
    -   PDS redirects User back to `/oauth/callback?code=...`.
    -   App calls `client.callback(params)`.
    -   `client` exchanges `code` for `tokens`.
    -   `client` saves tokens to `SessionStore`.
    -   App saves `session.did` to the browser cookie.
4.  **Usage**:
    -   On subsequent requests, App reads DID from browser cookie.
    -   App loads OAuth tokens from `SessionStore` using the DID.
    -   App creates an `Agent` to make API calls.