Messenger/specs.md

Project Spec — Realtime Chat & Calls App

This document is a brief for Claude Code (plan mode). Read it fully, then propose a plan before writing any code. Build the skeleton first, then implement part by part with check-ins. Do NOT scaffold the whole thing in one pass. See "How to work" (section 11) — it is as important as the architecture.

---

1. What we are building

A self-hosted, cross-platform messaging app with:

• Production-grade auth: register, login, token refresh, logout, with username, display name, avatar, and optional phone number — a Telegram-style profile model (see section 4).
• 1:1 direct messages and group rooms (Discord/Slack-shaped).
• Media messages: voice notes, video messages, images (files, not streamed).
• Live features: typing indicators, online/presence, last-seen, read receipts, edits, reactions — all delivered in realtime.
• Voice/video calls with screen share — group conferences and 1:1. This is a LATER phase (Phase 8). Do not scaffold call/WebRTC code until the chat core is working and I say so.

Targets: web, iOS, Android, and desktop (macOS + Windows).

Everything server-side runs in Docker Compose — the backend included, not just the supporting services. See section 9.

2. Core mental model (read this before anything else)

The realtime transport (Centrifugo) is a dumb, fast pipe, NOT the chat server. The backend is the brain.

Sending is over REST; receiving is over the WebSocket. This split is deliberate and is the most common thing people get wrong — do not "optimize" it away:

1. Send (client → server): a normal REST POST to the backend. The client's realtime socket is effectively receive-only. Sending must go through the backend because that is the only place validation, membership checks, persistence, server-assigned IDs, ordering, and rate-limiting can happen.
2. The backend authorizes, writes to Postgres (source of truth), then calls Centrifugo's HTTP API to publish into the channel.
3. Receive (server → client): Centrifugo fans the event out over the WebSocket to all subscribers — including the original sender, so all their devices stay in sync and they get the same server-assigned ID and ordering as everyone else. The sender renders the message from the socket echo, NOT from the REST response.

Do NOT let clients publish chat messages directly through Centrifugo, and do NOT tunnel sends through Centrifugo RPC — a plain REST POST reaches the same backend endpoint more simply, and send latency is dominated by the DB write anyway.

Channel model

• room:<roomId> — one channel per room; all members subscribe.
• user:<userId> — one personal channel per user. DMs are delivered by publishing the message into BOTH participants' personal channels; the client routes by conversationId in the payload. Scales to one subscription per user regardless of conversation count, and doubles as the notification / unread / "added to room" / read-receipt channel.

Two auth gates (keep them separate) — see section 4 for the full auth design

• Connection auth: backend mints a Centrifugo JWT (shared secret with Centrifugo) after the user is authenticated; Centrifugo verifies the signature — no backend call per connection. This is a SEPARATE token from the app's own access token.
• Subscription auth: use the subscribe-proxy pattern — Centrifugo calls a backend endpoint on each subscribe to check Postgres membership ("can user U join channel C?"). Reflects current DB state (kicked users lose access immediately). Personal-channel subscriptions are authorized by matching the token's user id.

Boundaries to respect

• Centrifugo history is a short recovery buffer (reconnect replay), NOT the message store. Load conversation history from Postgres via REST.
• Server-assigned monotonic message IDs + ordering and client-side dedupe are required from day one (messages arrive both live and via history load, and can overlap).
• On reconnect: subscribe FIRST, buffer incoming live events, THEN load history via REST, then merge + dedupe. Ordering of these two steps prevents "missing message" gaps.
• Media (voice notes / video messages / images) upload to object storage (MinIO) via the backend (presigned URLs); only a reference (URL + metadata) is published through the channel. Never push binary through Centrifugo.

3. Event taxonomy (how every realtime feature is handled)

Every live feature is just another event on the same receive socket. There is no separate system for typing vs presence vs messages — you publish different event types onto the same channels and the one socket carries them all. Each event falls into exactly one bucket:

Bucket A — Durable + must be correct → through the backend (persist, then publish)

The "brain" rule applies: REST in, backend validates + writes to Postgres, backend publishes to the relevant channel, clients receive over the socket.

• message.new — a new chat message.
• message.edit — edited message (store edit + edited_at).
• message.delete — soft delete.
• reaction.add / reaction.remove — emoji reactions.
• read.receipt — "user X has read up to message N" (updates read_state, published to conversation participants so checkmarks update live).
• last_seen — timestamp written to Postgres on disconnect or periodically; loaded via REST with conversation metadata. Durable because it must survive restarts and be queryable.
• room.membership — added to / removed from a room (published to the affected user's personal channel).
• profile.update — display name / avatar / username changes (published to that user's personal channel so contacts see the update live).

Bucket B — Ephemeral + throwaway → published to the channel, NOT persisted

No database write. Backend involvement optional (a tiny fire-and-forget REST call, or a constrained client-side publish, is acceptable here precisely because there is nothing to validate or store — worst case a spurious flicker).

• typing.start / typing.stop — published to room:<id> or the DM's channels; auto-clears on the client after ~3s if no follow-up. High-frequency, never stored.
• recording.audio / recording.video — "recording a voice note…" style indicators.

Bucket C — Connection-derived → Centrifugo built-in presence, no code of your own

• presence / online status — use Centrifugo's built-in channel presence (join/leave events, "who is subscribed"). Room online lists come from presence on room:<id>; a user's global online dot is derived from whether they hold an active user:<id> connection. Subscribe to presence updates on the socket.

Rule of thumb for any future feature: if it must be correct and durable → Bucket A. If it's throwaway → Bucket B. If it's "who's connected" → Bucket C. Define the event type, publish it, handle it on the client — never stand up new infrastructure.

All event type names and payload shapes live in the shared core package (section 6).

4. Auth & user identity (production-grade — Telegram-style profile)

Auth is security-critical and hard to change later. Use vetted, well-established building blocks — DO NOT hand-roll crypto, hashing, or token logic. Where a mature library exists (password hashing, JWT handling), use it.

Identity / profile model

• username — unique, immutable-ish public handle (like Telegram @handle). Case-insensitive unique. Used for search / mentions / DM initiation. Required.
• display_name — freely editable, non-unique, shown in UI. Required.
• avatar — optional image, uploaded to MinIO, stored as a reference (URL + metadata), same upload path as media messages. Changing it emits profile.update (Bucket A).
• phone number — OPTIONAL (like Telegram, not required to have an account). If present, stored normalized (E.164). May be used later for contact discovery; keep it optional and privacy-controlled from day one.
• email — decide in planning whether email is the primary credential or optional. Default assumption: email OR username + password for login; phone optional and additive. Confirm with me before locking this.

Credentials & registration

• Register: username + display_name + password (+ optional email/phone). Enforce username uniqueness and a sane password policy (length-based, not silly complexity rules).
• Password hashing: use argon2id (preferred) or bcrypt via a maintained library. Never store plaintext, never invent a hashing scheme, never use fast hashes (MD5/SHA).
• Login: credential + password → issue an access token + refresh token (see below).
• Rate-limit login and register endpoints to blunt credential stuffing / enumeration. Return non-enumerating errors ("invalid credentials", not "no such user").

Token model (this is the production-grade part — get it right)

Two app tokens, plus the separate Centrifugo token:

• Access token — short-lived JWT (e.g. ~15 min), sent on every REST request (Authorization: Bearer). Stateless; carries user id + minimal claims. Never long-lived.
• Refresh token — long-lived, opaque (random, not a JWT), stored server-side (hashed) in a refresh_tokens table, one row per device/session. Used only at the /auth/refresh endpoint to mint a new access token.
• Refresh rotation with reuse detection: every refresh issues a NEW refresh token and invalidates the old one. If an already-used (rotated-out) refresh token is presented again, treat it as theft — revoke the whole token family / session and force re-login. This is a required behavior, not optional.
• Centrifugo connection token — a SEPARATE short-lived JWT minted by the backend (signed with the Centrifugo shared secret) once the user is authenticated. Do not reuse the app access token for Centrifugo. The client fetches/refreshes it via an authenticated backend endpoint.

Sessions & devices

• refresh_tokens (or sessions) table tracks each active session: user_id, hashed token, device/user-agent info, created_at, last_used_at, expires_at, revoked_at.
• Logout revokes the current session's refresh token. Support "log out this device" and "log out all devices" (revoke all rows for the user).
• Multi-device is expected (Telegram-style): a user may have several active sessions at once; the personal-channel model already supports fan-out to all their devices.

Endpoints (starting set — refine in planning)

POST /auth/register, POST /auth/login, POST /auth/refresh, POST /auth/logout, POST /auth/logout-all, GET /me, PATCH /me (display_name / avatar / phone), GET /auth/sessions, POST /auth/centrifugo-token, GET /users/:username (public profile), avatar upload endpoint (presigned, via the media path).

Security requirements (non-negotiable)

• Passwords hashed with argon2id/bcrypt via a library; never logged, never returned.
• Refresh tokens opaque + hashed at rest + rotated + reuse-detected.
• Access tokens short-lived; secrets from env (section 9), never committed.
• Rate-limit auth endpoints; non-enumerating error messages.
• Validate all inputs against JSON Schema from core.
• Treat the Centrifugo token as separate and short-lived.
• DO NOT hand-roll cryptography or token schemes — use maintained libraries and standard patterns. Flag to me if a requirement seems to need custom crypto (it almost never does).

5. Stack (decided — do not re-litigate)

• Language everywhere: TypeScript.
• Monorepo: single repo, pnpm workspaces. (NOT separate repos — shared code is imported by source so type changes surface as immediate compile errors.)
• Backend framework: Fastify. (NestJS considered and rejected: too much ceremony/DI for a small team and a realtime/event-shaped workload.)
• Auth libraries: argon2 (or bcrypt) for hashing; a maintained JWT library for access tokens; opaque random refresh tokens stored hashed. No custom crypto.
• Validation: JSON Schema via Fastify's built-in support, sourced from core.
• Realtime transport: Centrifugo (self-hosted, runs in Docker Compose).
• DB: Postgres 16 (source of truth). Redis for Centrifugo scaling + history/recovery (and available for auth rate-limiting / token-family tracking if useful).
• Object storage: MinIO (S3-compatible) — media messages AND avatars.
• Web frontend: React + TypeScript + Vite.
• Mobile frontend: React Native + Expo + TypeScript.
• Desktop: thin Tauri (preferred) or Electron shell wrapping the web build.
• Calls (LATER, Phase 8): LiveKit (SFU) + coturn (TURN over TLS/443). Not now.

6. Monorepo layout

/
├── package.json                 # pnpm workspace root
├── pnpm-workspace.yaml
├── tsconfig.base.json
├── docker-compose.yml           # base: all backend-side services (see section 9)
├── docker-compose.override.yml  # local dev conveniences (hot reload, exposed ports)
├── docker-compose.prod.yml      # deploy overrides (restart policies, no source mounts)
├── .env.example                 # every env var documented; real .env is gitignored
├── packages/
│   ├── core/                    # THE KEYSTONE — platform-agnostic, imported by all
│   │   ├── src/
│   │   │   ├── types/           # message/event/API payload types + user/profile types
│   │   │   ├── events/          # event type constants + payloads (section 3 taxonomy)
│   │   │   ├── schemas/         # JSON Schemas (backend validates, clients type off these)
│   │   │   ├── channels/        # channel-name builders: room:<id>, user:<id>
│   │   │   ├── realtime/        # Centrifugo SDK wrapper (UI-agnostic)
│   │   │   ├── api/             # typed API client functions (incl. auth flows)
│   │   │   └── messages/        # dedupe + ordering logic
│   │   └── package.json
│   ├── backend/                 # Fastify service; imports core; runs in Docker
│   │   ├── src/
│   │   │   ├── routes/          # auth, users/profile, messages, rooms, conversations, media, subscribe-proxy
│   │   │   ├── plugins/         # db, redis, centrifugo client, auth/jwt, rate-limit
│   │   │   ├── auth/            # hashing, token issue/rotate/verify, session management
│   │   │   ├── db/              # migrations + queries
│   │   │   └── server.ts
│   │   ├── Dockerfile           # multi-stage; see section 9
│   │   └── package.json
│   ├── web/                     # React + Vite; imports core
│   │   ├── Dockerfile           # optional: containerized static build for deploy
│   │   └── package.json
│   ├── mobile/                  # React Native + Expo; imports core (not containerized)
│   │   └── package.json
│   └── desktop/                 # Tauri/Electron shell over web build (not containerized)
│       └── package.json
├── infra/
│   ├── centrifugo/config.json   # shared JWT secret, subscribe proxy, namespaces
│   ├── postgres/init/           # init SQL if needed
│   └── nginx/                   # reverse proxy config (routes /api and /connection/websocket)
└── PROJECT_SPEC.md

Rules for core

• No react-dom or react-native imports anywhere in core. It is pure TS.
• Keep React hooks / state logic UI-agnostic where possible so it can migrate into core later. Do NOT bake DOM/RN assumptions into the Centrifugo/API wrappers.
• One source of truth for payload shapes, event definitions, AND auth/profile types: all live here; backend and clients both consume them.

7. Data model (starting point — refine in planning)

Tables (Postgres): users, refresh_tokens (aka sessions), rooms, room_members, conversations (for DMs), messages, reactions, read_state.

• users: id, username (unique, case-insensitive), display_name, avatar_ref (nullable), phone (nullable, E.164), email (nullable or primary — confirm in planning), password_hash, created_at, last_seen_at.
• refresh_tokens: id, user_id, token_hash, device/user-agent, created_at, last_used_at, expires_at, revoked_at, family/rotation id for reuse detection.
• messages: server-assigned monotonic id/sequence (BIGSERIAL or per-room counter) + a stable id for client-side dedupe.
• Membership drives channel access (the subscribe-proxy checks these tables).
• Typing/presence/recording are NOT tables (Buckets B and C — not persisted).

8. Build phases (implement in this order)

Phase 0 — Skeleton + Docker. Monorepo tooling, workspaces, tsconfig, empty packages that build and import core. Full docker-compose.yml bringing up Centrifugo + Postgres + Redis

• MinIO + backend, with the dev override for hot reload. No features yet. Verify the whole stack boots with one docker compose up and the backend reaches every service.

Phase 1 — Auth (production-grade). Implement section 4 in full: register, login, refresh with rotation + reuse detection, logout / logout-all, sessions table, argon2 hashing, access

• refresh tokens, /me + PATCH /me, rate-limiting on auth endpoints. This is the foundation everything else authenticates against — get it solid before features.

Phase 2 — Realtime connection. Backend mints the separate Centrifugo token; web client connects its (receive-only) socket using it and subscribes to its personal channel via the subscribe-proxy. Prove authenticated end-to-end connectivity.

Phase 3 — Rooms + messaging. Room CRUD, membership, subscribe-proxy authorization, send-message REST endpoint → persist → publish to room:<id>. History load from Postgres. Server-assigned ids + client dedupe. message.new end to end.

Phase 4 — DMs. Personal-channel delivery (publish to both participants), conversation model, client routing by conversationId.

Phase 5 — Live features (event taxonomy). Typing (Bucket B), presence (Bucket C, built-in), last-seen (Bucket A), read receipts (Bucket A), edits + reactions (Bucket A), profile.update (Bucket A). Implement per the section-3 buckets.

Phase 6 — Media + avatars. MinIO presigned uploads; voice notes / video messages / images as references published through channels; user avatars via the same path.

Phase 7 — Mobile + desktop clients. React Native + Expo consuming the same core (reuse realtime + API + auth layer; platform-specific UI only). Then the Tauri/Electron desktop shell over the web build.

Phase 8 (LATER, separate effort) — Calls. LiveKit + coturn (added as new Docker Compose services), call signaling over Centrifugo (ring via personal channel), token minting in backend, screen share. Do NOT start until explicitly told. TURN-over-443 + simulcast are legitimate reliability engineering, NOT censorship circumvention (see section 12).

9. Docker & deployment (IMPORTANT — Docker Compose is the primary runtime)

Everything server-side runs in Docker Compose, for BOTH local development and deploy. The backend is containerized too — do not assume it runs on the host. Aim for a single docker compose up to bring up the entire backend stack locally.

Compose file strategy (use overrides, don't fork the file)

• docker-compose.yml — base definition of all services: backend, centrifugo, postgres, redis, minio, nginx. Sensible defaults, named volumes, a private network, healthchecks, and depends_on with condition: service_healthy so the backend waits for Postgres/Redis to be ready.
• docker-compose.override.yml — auto-loaded in local dev: mount backend source for hot reload (e.g. tsx watch / nodemon), expose service ports to the host, use dev secrets, seed data. Convenience only.
• docker-compose.prod.yml — explicit for deploy: restart: unless-stopped, NO source mounts (use the built image), secrets from real env, tighter exposure (only nginx faces the internet). Deploy with docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d.

Backend Dockerfile

• Multi-stage: a build stage (install pnpm, build core + backend) and a slim runtime stage (node:LTS-alpine or distroless, production deps only). The monorepo means the build stage must handle pnpm workspaces — build core first, then backend.
• Run as a non-root user. Add a HEALTHCHECK hitting a /health endpoint.
• .dockerignore to keep node_modules, build artifacts, and other packages out of context.

Services — requirements

• backend: depends_on postgres+redis (healthy), reads all config from env, exposes only to the internal network in prod (nginx proxies it). /health and /ready endpoints. Runs DB migrations on startup or via a one-shot migration service.
• centrifugo: official image, config from infra/centrifugo/config.json + env. Shared JWT secret via env, subscribe-proxy endpoint pointing at the backend service name, room: and user: namespaces defined, Redis engine + history enabled for recovery. Raise the nofile ulimit (e.g. 65536) — FD exhaustion is the first wall for a realtime server.
• postgres: version 16, named volume, healthcheck (pg_isready), init SQL mount if useful. Never expose to the internet in prod.
• redis: Centrifugo scaling + history/recovery; present from Phase 0 as the coordination layer future clustering depends on. Named volume if persistence wanted.
• minio: S3-compatible object storage for media + avatars; console + API, named volume, bucket bootstrap on startup.
• nginx: reverse proxy / TLS termination. Routes /api/* → backend and /connection/websocket → centrifugo, passing WebSocket upgrade headers correctly. In prod this is the only internet-facing service.

General Docker rules

• Secrets via env / .env (gitignored) — never baked into images or committed. Ship a fully documented .env.example (include all auth secrets: JWT signing key, Centrifugo shared secret, DB/Redis/MinIO creds).
• Named volumes for all stateful services (postgres, redis, minio) so data survives docker compose down.
• Private network for inter-service traffic; only nginx published to the host in prod.
• Pin image versions (no bare latest) for reproducibility.
• Every long-running service has a healthcheck; the backend uses them via depends_on.
• Local dev must be one command. Document it in the README the scaffold generates.

10. Scaling assumptions (design for, don't build yet)

• Backend and Centrifugo are stateless — no in-memory session state (sessions live in Postgres/Redis, not process memory). This is what lets them scale horizontally later (multiple backend and Centrifugo replicas behind nginx, coordinated by Redis).
• Media plane (LiveKit/coturn, Phase 8) stays physically separate from the control plane.
• Redis present from Phase 0 (coordination layer for later Centrifugo + LiveKit clustering).

11. How to work (IMPORTANT — follow this)

• Plan first. Before writing code, produce a plan for the current phase only and wait for my approval. Do not jump ahead to later phases.
• Explain before implementing. For each phase, briefly explain the approach and the reasoning behind key decisions before generating code. I prefer understanding the "why".
• Go part by part with check-ins. Implement one coherent piece, stop, let me review, then continue. Do not dump large amounts of generated code in one go.
• Do not add features I didn't ask for. No calls/WebRTC before Phase 8. No speculative abstractions.
• Ask when a decision is ambiguous rather than guessing, especially the data model, API shapes, event payloads, and the email-vs-username-vs-phone credential question in section 4.
• Respect the decided stack in section 5 — don't substitute frameworks or add heavy dependencies without flagging why.
• For auth, use vetted libraries and standard patterns — never hand-roll crypto or token logic. Flag anything that seems to need custom crypto.
• Keep the shared core package clean of platform-specific imports.
• Prefer the Docker Compose workflow (section 9) for anything that touches running services.