Developer Docs
Architecture, data model, and conventions for building Sangria.
This section is for people working on Sangria. It explains how the app is put together, the shared building blocks you're expected to reuse, and the workflow for shipping a change safely.
Stack at a glance
- Frontend — Next.js 16 (App Router) + React 19,
jotaifor local state andnuqsfor URL state, Tailwind CSS. - Backend — Convex (self-hosted locally): schema, queries, mutations, actions, HTTP routes, scheduled functions, and components (rate-limiter, workpool).
- Realtime media — LiveKit powers huddles.
- Shells — Electron (desktop) and Capacitor (iOS/Android), plus a PWA.
- Package manager —
bun.
Start here
Architecture
How the pieces fit and how a request flows.
Conventions
The helpers you must reuse — authz, routes, enums, rate limits.
Data model
The Convex schema, table by table.
Notifications pipeline
The durable outbox + workpool fan-out pattern.
Data migrations
The source-agnostic migration framework, and the Mattermost import built on it.
Integrations API
Incoming webhooks, the bot API, and signed outgoing events.
Testing & verify
The convex-test harness and the pre-commit checklist.
Definition of Done
Every backend function needs auth, resource-level authorization, the right public/internal boundary, rate limiting where it writes durable state, and a test. See Conventions and Testing before opening a PR.