# 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" at the
> bottom — it is as important as the architecture.

---

## 1. What we are building

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

- **1:1 direct messages and group messages** (Telegram-shaped).
- **Media messages**: voice notes, video messages, images, videos (files).
- **Voice/video calls with screen share** — group conferences and 1:1. **This is a LATER
  phase. Do not scaffold call/WebRTC code until the chat core is working and I say so.**

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

## 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**. The message-send flow is deliberately:

1. Client POSTs "send message" to the backend REST API (the client's realtime socket is
   effectively **receive-only**).
2. Backend authorizes, writes the message to Postgres (source of truth), then calls
   Centrifugo's HTTP API to publish into the channel.
3. Centrifugo fans it out to subscribers.

Do not let clients publish directly through Centrifugo. All business logic, validation,
and persistence live in the backend.

### 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. This scales to one subscription per user regardless of conversation count,
  and doubles as the notification / unread / "added to room" channel.

### Two auth gates (keep them separate)

- **Connection auth**: backend mints a JWT (shared secret with Centrifugo) at login;
  Centrifugo verifies the signature — no backend call per connection.
- **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?").
  This 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 message IDs + ordering** and **client-side dedupe** are required from
  day one (messages can arrive both live and via history load). These are painful to
  retrofit.
- 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. 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 was considered and rejected: too much
  ceremony/DI for a small team and a realtime/event-shaped workload.)
- **Validation:** JSON Schema via Fastify's built-in support, sourced from the shared package.
- **Realtime transport:** Centrifugo (self-hosted, external service).
- **DB:** Postgres 16 (source of truth). **Redis** for Centrifugo scaling + history/recovery.
- **Object storage:** MinIO (S3-compatible).
- **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):** LiveKit (SFU) + coturn (TURN over TLS/443). Not now.

## 4. Monorepo layout

```
/
├── package.json                 # pnpm workspace root
├── pnpm-workspace.yaml
├── tsconfig.base.json
├── packages/
│   ├── core/                    # THE KEYSTONE — platform-agnostic, imported by all
│   │   ├── src/
│   │   │   ├── types/           # message/event/API payload types
│   │   │   ├── 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
│   │   │   └── messages/        # dedupe + ordering logic
│   │   └── package.json
│   ├── backend/                 # Fastify service; imports core
│   │   ├── src/
│   │   │   ├── routes/          # auth, messages, rooms, conversations, media, subscribe-proxy
│   │   │   ├── plugins/         # db, redis, centrifugo client, auth/jwt
│   │   │   ├── db/              # migrations + queries
│   │   │   └── server.ts
│   │   └── package.json
│   ├── web/                     # React + Vite; imports core
│   │   └── package.json
│   ├── mobile/                  # React Native + Expo; imports core
│   │   └── package.json
│   └── desktop/                 # Tauri/Electron shell over web build (config-heavy)
│       └── package.json
├── infra/                       # docker-compose for Centrifugo, Postgres, Redis, MinIO
│   ├── docker-compose.yml
│   └── centrifugo/config.json
└── 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: types + JSON Schemas live here, backend and
  clients both consume them.

## 5. Data model (starting point — refine in planning)

Tables (Postgres): `users`, `rooms`, `room_members`, `conversations` (for DMs),
`messages`, `read_state` (per-user, per-conversation last-read message id).

- `messages` needs a **server-assigned monotonic id/sequence** (e.g. BIGSERIAL or per-room
  counter) and a stable id used for client-side dedupe.
- Membership drives channel access (the subscribe-proxy checks these tables).

## 6. Build phases (implement in this order)

**Phase 0 — Skeleton.** Monorepo tooling, workspaces, tsconfig, empty packages that build
and import `core`. `infra/docker-compose.yml` bringing up Centrifugo + Postgres + Redis +
MinIO locally. No features yet. Verify everything boots.

**Phase 1 — Auth + connection.** User signup/login in backend; JWT minting for Centrifugo;
web client connects its (receive-only) socket and subscribes to its personal channel via
the subscribe-proxy. Prove end-to-end connectivity.

**Phase 2 — 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. Web client sends/receives in a room.

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

**Phase 4 — Media messages.** MinIO presigned uploads; voice notes / video messages /
images as references published through channels.

**Phase 5 — Mobile client.** React Native + Expo consuming the same `core`. Reuse realtime

- API layer; platform-specific UI only.

**Phase 6 — Desktop shell.** Tauri/Electron over the web build.

**Phase 7 (LATER, separate effort) — Calls.** LiveKit + coturn, call signaling over
Centrifugo (ring via personal channel), token minting in backend, screen share. Do NOT
start until explicitly told; video across platforms is the hardest part of the project and
gets its own focused phase.

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

- Backend and Centrifugo are **stateless** — no in-memory session state; everything in
  Postgres/Redis. This is what lets them scale horizontally later.
- Media plane (LiveKit/coturn) stays **physically separate** from the control plane.
- Redis is present from Phase 0 (coordination layer for later Centrifugo + LiveKit clustering).

## 8. 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 7. No speculative
  abstractions.
- **Ask when a decision is ambiguous** rather than guessing, especially on the data model
  and API shapes.
- **Respect the decided stack** in section 3 — don't substitute frameworks or add heavy
  dependencies without flagging why.
- Keep the shared `core` package clean of platform-specific imports.

## 9. Legal / deployment note (context, not a task)

Deployment target includes the Russian Federation. There are messenger-registration and
data-localization rules that carry real liability; this is for the humans to handle with
local legal advice — not something to implement or work around in code. Network reliability
on poor connections (TURN-over-443, simulcast) is legitimate engineering and belongs in the
LATER calls phase, but is not a censorship-circumvention feature and should not be built as one.