# dpcodes008/sub-rosa architecture

> Architecture diagram of the GitHub repository dpcodes008/sub-rosa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dpcodes008/sub-rosa
- Repository: https://github.com/dpcodes008/sub-rosa

## Overview

**Sub Rosa** is a **real-time, room-based ephemeral chat system**:
- **Frontend:** static HTML pages with browser-side JS (implicit) for login, rooms UI, and WebSocket client behavior.
- **Backend:** **FastAPI** service providing HTTP routes (auth + room creation + static serving) and **WebSocket** endpoints for real-time messaging.
- **State store:** **Redis** for room state and TTL-driven expiry (rooms auto-destruct).
- **Security model:** server is a **“dumb relay”** for messages; **no message persistence**. Auth is **passwordless magic-link email**, and **WebSocket access is gated before `accept()`** via a **short-lived session token**.

- Messages are transient WS frames only (not stored).
- Rooms/state exist with TTL in Redis.
- Auth is a two-token flow (magic-link token → session token).
- WebSocket handshake is authorization-enforced.

From the tree:

##### Backend (FastAPI, Python)
- `app/main.py`: entrypoint; HTTP routes + serves `static/*`
- `app/ws.py`: WebSocket lifecycle; validates session before accept; room-scoped broadcast/relay
- `app/rooms.py`: room creation/management; TTL policy; Redis interactions
- `app/auth.py`: magic-link token + session token creation/verification; domain allowlist (`@nitc.ac.in`)
- `app/emailer.py`: SMTP integration for delivering magic links
- `app/config.py`: configuration (Redis URL, SMTP creds, token TTLs, secrets)
- `app/crypto.py`: reserved for Phase 7 E2EE (future component)

##### Frontend (Static)
- `static/login_page.html`: magic-link login UI
- `static/rooms.html`: chat UI + WS client
- `static/ws_test.html`: WS testing page

##### Dependencies / build
- `requirements.txt`: Python deps (FastAPI, redis client, jwt libs, etc.)
- `package.json`, `package-lock.json`: indicates some Node-based tooling (likely for dev utilities or bundling; but since UI is static HTML, treat Node as “optional build/tooling” unless README says otherwise).

- **Ephemeral Rooms:** created with TTL; auto-expire; enforced server-side; TTL at Redis level (Phase 5)
- **Real-time Messaging:** only via WebSockets; server relays; never persists
- **Ephemeral Messages:** TTL included, but **client enforces expiry** (important boundary: server does not store, client removes)
- **Authentication:** magic-link email; only allowed domain; session token required for HTTP + WS
- **WebSocket Access Control:** must validate session token **before** `accept()`

##### Static asset delivery
- Browser → FastAPI (`GET /login_page.html`, `/rooms.html`, etc.)

##### Magic link request
- Browser (login form) → FastAPI Auth (`POST /auth/request-link` or similar)
- FastAPI Auth → SMTP (Gmail)
- SMTP → User’s inbox (can be implied)

##### Magic link verification
- Browser clicks link → FastAPI Auth (`GET /auth/verify?token=...`)
- FastAPI Auth → returns **Session Token** (JWT or signed token)

##### Room creation / join (HTTP control plane)
- Browser → FastAPI Room Service (`POST /rooms`, `POST /rooms/join`, etc.)
Must include Session Token

##### Room state persistence
- FastAPI Room Service ↔ Redis
“Room keys w/ TTL”, “auto expiry”, “crash resilient”

##### WebSocket connection (data plane)
- Browser → FastAPI WebSocket (`ws://.../ws?room=...` + token)
Critical annotation: **“Validate session token BEFORE accept()”**

##### Message relay
- Browser ↔ WebSocket Gateway (FastAPI `ws.py`)
- WebSocket Gateway → Other clients in same room
Explicit callout: **No persistence** (messages do not go to Redis)

##### Message TTL (client-side)
- A note: “Server never stores message history”

##### Architectural patterns / principles
- **Control plane vs Data plane**
- Control plane: HTTP for auth + room creation
- Data plane: WS for chat messages only
- **State boundary**
- Redis stores *room state only*, not messages
- **Untrusted server posture**
- Server relays, does not interpret/store content
- **Token separation**
- Magic-link token (one-time, short TTL)
- Session token (short-lived, reused, required for WS)

##### Technologies / libraries that matter
- FastAPI (Python)
- Uvicorn (runtime, optional label)
- Redis (TTL)
- SMTP (Gmail App Password)
- WebSockets
- JWT/signed tokens (whatever `auth.py` uses)

##### “Don’t overthink it”: split into as many components as possible (but keep correctness)

- Browser
- FastAPI Backend (subcomponents listed)
- Redis
- SMTP
- Trust boundaries (Internet vs backend network)

##### Message relay within room (no persistence) + client TTL deletion

- Browser: `login_page.html`
- Browser: `rooms.html` (WS client + TTL deletion)
- FastAPI: `main.py` (routes + static)
- FastAPI: `auth.py` (magic link + session tokens)
- FastAPI: `emailer.py` (SMTP)
- FastAPI: `rooms.py` (room TTL + Redis keys)
- FastAPI: `ws.py` (WS gateway; pre-accept auth; room broadcast)
- Redis: room state + TTL expiry
- SMTP: Gmail

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Actors / Clients
    %% =========================
    User["User"]:::external

    subgraph "Client (Browser)"
        LoginUI["Login Page UI"]:::frontend
        RoomsUI["Rooms / Chat UI\n(WS client + client-side message TTL deletion)"]:::frontend
        WSTestUI["WebSocket Test Page"]:::frontend

        subgraph "Client-side State & Policy"
            SessionStore["Session Token Storage\n(cookie/localStorage)"]:::security
            ClientTTL["Message TTL deletion\n(client-enforced)"]:::privacy
        end
    end

    %% =========================
    %% Edge / Network Boundary
    %% =========================
    Internet["Internet"]:::boundary

    %% =========================
    %% Backend (FastAPI)
    %% =========================
    subgraph "Backend (FastAPI + Uvicorn)"
        Config["Configuration / Secrets\n(Redis URL, SMTP creds, token TTLs, secrets)"]:::config

        subgraph "HTTP Control Plane"
            Main["HTTP Router + Static Server\n(Serves static/*)"]:::backend
            Auth["Auth Service\n(Magic-link token -> Session token)\n(Domain allowlist)"]:::security
            Rooms["Room Service\n(Room creation/management + TTL policy)"]:::backend
            Emailer["Email Sender\n(SMTP integration)"]:::backend
        end

        subgraph "WebSocket Data Plane"
            WSGateway["WebSocket Gateway / Relay\n(Validate session BEFORE accept())\n(Room-scoped broadcast)"]:::ws
            NoPersist["NO message persistence\n(Messages are transient WS frames only)"]:::privacy
        end

        subgraph "Future (Phase 7)"
            Crypto["E2EE / Crypto Module (planned)\n(Server stays blind)"]:::future
        end
    end

    %% =========================
    %% Data Stores / External Services
    %% =========================
    Redis[("Redis\nRoom state only\nKey TTLs enforce room expiry")]:::datastore
    SMTP["SMTP Provider\n(Gmail SMTP)"]:::external
    Mailbox["User Inbox"]:::external

    %% =========================
    %% Tooling / Dependencies (non-runtime)
    %% =========================
    subgraph "Project Dependencies / Tooling"
        PyDeps["Python Dependencies\n(FastAPI, Redis client, JWT libs, etc.)"]:::tooling
        NodeTooling["Node Tooling (optional)\n(dev/build utilities)"]:::tooling
        NodeLock["Node Lockfile"]:::tooling
    end

    %% =========================
    %% Flows: Static assets
    %% =========================
    User -->|"uses"| LoginUI
    User -->|"uses"| RoomsUI
    User -->|"uses"| WSTestUI

    LoginUI -->|"HTTP GET static"| Internet -->|"HTTP GET static"| Main
    RoomsUI -->|"HTTP GET static"| Internet -->|"HTTP GET static"| Main
    WSTestUI -->|"HTTP GET static"| Internet -->|"HTTP GET static"| Main

    %% =========================
    %% Flows: Magic link auth (two-token)
    %% =========================
    LoginUI -->|"HTTP POST auth_request_link"| Internet -->|"HTTP POST"| Auth
    Auth -->|"SMTP send_magic_link\n(MagicLinkToken,short_TTL)"| Emailer
    Emailer -->|"SMTP"| SMTP -->|"email_delivery"| Mailbox
    Mailbox -->|"user_clicks_magic_link"| User

    User -->|"opens_magic_link"| Internet -->|"HTTP GET verify?token=MagicLinkToken"| Auth
    Auth -->|"HTTP response: issue SessionToken\n(short_TTL)"| Internet -->|"HTTP response"| LoginUI
    LoginUI -->|"store SessionToken"| SessionStore

    %% =========================
    %% Flows: Room creation/join (control plane)
    %% =========================
    RoomsUI -->|"HTTP POST rooms_create/join\n(with SessionToken)"| Internet -->|"HTTP POST"| Rooms
    Rooms -->|"Redis SET/EXPIRE\n(room_key + TTL)"| Redis
    Redis -->|"TTL expiry auto-destroys rooms"| Redis

    %% =========================
    %% Flows: WebSocket connect (data plane) with pre-accept auth gate
    %% =========================
    RoomsUI -->|"WS upgrade ws://.../ws?room=... + SessionToken"| Internet -->|"WS upgrade"| WSGateway
    WSGateway -->|"validate SessionToken\nBEFORE accept()"| Auth
    WSGateway -->|"optional: room validation/membership"| Rooms
    Rooms -->|"Redis GET room_state"| Redis

    %% =========================
    %% Flows: Message relay (no persistence)
    %% =========================
    RoomsUI <-->|"WS frames\n(chat messages,ephemeral)"| WSGateway
    WSGateway -->|"broadcast to other clients\n(same room_id)"| Internet
    WSGateway -.->|"no_store"| NoPersist
    NoPersist -.->|"NOT written to Redis"| Redis

    %% =========================
    %% Client-side TTL for messages
    %% =========================
    RoomsUI -->|"render message"| ClientTTL
    ClientTTL -->|"delete after message_TTL\n(client enforced)"| RoomsUI

    %% =========================
    %% Future E2EE placement (dashed)
    %% =========================
    Crypto -.->|"future: encrypt/decrypt on client"| RoomsUI
    Crypto -.->|"future: server relays ciphertext only"| WSGateway

    %% =========================
    %% Config wiring
    %% =========================
    Config -->|"env/config"| Main
    Config -->|"env/config"| Auth
    Config -->|"env/config"| Rooms
    Config -->|"env/config"| Emailer
    Config -->|"env/config"| WSGateway
    Config -->|"Redis URL"| Redis
    Config -->|"SMTP creds"| SMTP

    %% =========================
    %% Dependency/tooling relations (informational)
    %% =========================
    PyDeps -.->|"runtime deps"| Main
    PyDeps -.->|"runtime deps"| Auth
    PyDeps -.->|"runtime deps"| Rooms
    PyDeps -.->|"runtime deps"| Emailer
    PyDeps -.->|"runtime deps"| WSGateway
    NodeTooling -.->|"optional build/dev"| LoginUI
    NodeTooling -.->|"optional build/dev"| RoomsUI
    NodeTooling -.->|"optional build/dev"| WSTestUI
    NodeLock -.->|"pins tooling deps"| NodeTooling

    %% =========================
    %% Click Events (from component_mapping)
    %% =========================
    click Main "https://github.com/dpcodes008/sub-rosa/blob/main/app/main.py"
    click WSGateway "https://github.com/dpcodes008/sub-rosa/blob/main/app/ws.py"
    click Rooms "https://github.com/dpcodes008/sub-rosa/blob/main/app/rooms.py"
    click Auth "https://github.com/dpcodes008/sub-rosa/blob/main/app/auth.py"
    click Emailer "https://github.com/dpcodes008/sub-rosa/blob/main/app/emailer.py"
    click Config "https://github.com/dpcodes008/sub-rosa/blob/main/app/config.py"
    click Crypto "https://github.com/dpcodes008/sub-rosa/blob/main/app/crypto.py"
    click LoginUI "https://github.com/dpcodes008/sub-rosa/blob/main/static/login_page.html"
    click RoomsUI "https://github.com/dpcodes008/sub-rosa/blob/main/static/rooms.html"
    click WSTestUI "https://github.com/dpcodes008/sub-rosa/blob/main/static/ws_test.html"
    click PyDeps "https://github.com/dpcodes008/sub-rosa/blob/main/requirements.txt"
    click NodeTooling "https://github.com/dpcodes008/sub-rosa/blob/main/package.json"
    click NodeLock "https://github.com/dpcodes008/sub-rosa/blob/main/package-lock.json"

    %% =========================
    %% Styles
    %% =========================
    classDef frontend fill:#d6ecff,stroke:#1b6ca8,stroke-width:1.5px,color:#0b2b40
    classDef backend fill:#e7f7ea,stroke:#2f7d32,stroke-width:1.5px,color:#0b2b40
    classDef ws fill:#dcfce7,stroke:#15803d,stroke-width:2px,color:#052e16
    classDef datastore fill:#f3f4f6,stroke:#4b5563,stroke-width:1.5px,color:#111827
    classDef external fill:#fff7ed,stroke:#c2410c,stroke-width:1.5px,color:#431407
    classDef security fill:#ffe4e6,stroke:#be123c,stroke-width:1.8px,color:#4a0b1f
    classDef privacy fill:#f5f3ff,stroke:#6d28d9,stroke-width:1.5px,color:#2e1065
    classDef future fill:#ffffff,stroke:#6b7280,stroke-width:1.5px,stroke-dasharray: 6 4,color:#111827
    classDef config fill:#fef9c3,stroke:#a16207,stroke-width:1.5px,color:#3b2f05
    classDef tooling fill:#e5e7eb,stroke:#6b7280,stroke-width:1.2px,color:#111827
    classDef boundary fill:#ffffff,stroke:#94a3b8,stroke-width:2px,stroke-dasharray: 4 4,color:#0f172a
```
