Sauci/docs/architecture/system.md

System architecture

Sauci is an npm workspace coordinated by Turborepo.

Component	Technology	Responsibility
Mobile	Expo / React Native / Expo Router	primary customer product
Admin	Vite / React	content and administrative operations
Web	Next.js App Router	marketing, policies, redemption
API	Node.js / Hono / PostgreSQL	customer data, authorization, and workflows
Worker	Node.js / PostgreSQL-backed jobs	scheduled and asynchronous work
Auth	Hosted Supabase Auth	identity issuance and account recovery only
MCP	Hono / MCP SDK	authenticated internal administrative tools
Shared	TypeScript types	cross-application contracts only

Trust boundaries

• Mobile and web use public Supabase credentials only for Auth. Application data is available exclusively through the versioned Sauci API.
• The API verifies Supabase access tokens against the hosted public JWKS and derives user, couple, and administrative authority server-side.
• PostgreSQL and object storage are private infrastructure and are never exposed directly to clients.
• Administrative access requires both an authenticated identity and role checks.
• The hosted Auth service-role credential is confined to the API's Auth Admin account-deletion and identity-enrichment calls; it is not a product-data credential and is not provided to the worker, MCP, or clients.
• MCP authenticates callers with SAUCI_MCP_API_KEY, then calls the standalone admin API using SAUCI_ADMIN_API_URL and a scoped SAUCI_ADMIN_API_TOKEN. It has no database, Supabase data-plane, or storage credentials. The API maps the service token to an active admin identity and owns authorization and audit evidence for every mutation.
• Local product-data verification uses only loopback PostgreSQL/API services. Authenticated native acceptance may use only the designated hosted non-production Auth project and disposable fixture identities, never production.

Product flow

Two profiles join a couple, answer questions independently, and an API transaction creates a match when answers are compatible. Authenticated domain events surface matches and chat messages to the partner.

Change boundaries

• Database shape: API-owned migration plus shared contracts and affected clients.
• API contract: integration tests plus calling UI/store behavior.
• Shared contract: update every consumer in the same change.
• UI flow: component/unit coverage and observable E2E evidence.