How dpcodes008/sub-rosa works
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