Welcome
Engineering handbook for SOMA — architecture, data model, agent stack, ops runbook.
SOMA is a personal AI assistant with knowledge-graph memory. This site is the engineering handbook: architecture, data model, agent stack, and ops runbook.
Where to start
- New to the codebase? → Introduction → System architecture → Data model.
- Touching the agent? → Models & stack → Tool registry.
- Deploying / debugging? → Runbook, Production state.
- Why this shape? → Design philosophy, Non-goals.
Stack at a glance
| Runtime | Node 22 · TypeScript 5 strict · pnpm 10 · Turborepo 2 |
| Agent | Mastra on Vercel AI SDK · Claude Sonnet 4.5 (Opus 4.5 for synthesis) |
| Embeddings | Voyage-3-large (1024d) + rerank-2 |
| DB | Supabase Postgres 16 + pgvector (HNSW) · Drizzle ORM |
| Queue / Cron | Inngest Cloud |
| Hosting | Vercel Pro · Supabase Pro · Cloudflare DNS |
| Secrets | Doppler (project soma, config prod) |
| Observability | Langfuse · Sentry · PostHog · Axiom |
Live surfaces
- Web · soma-ai.cc
- Bot · @happ_soma_bot
- Status ·
/api/health
The four principles
- One table per kind, not per noun. Every user-facing noun is a row in
entities. New domain = newtype, not a new migration. - Tools own writes. Every DB mutation flows through a Mastra tool. UIs and bots never touch the DB directly.
- RLS on every table.
user_id = auth.uid()policies on every table, even on single-user MVP. - Zod in
@soma/coreis the source of truth. One schema → backend validation + TS types + frontend forms.