Overview
Monorepo map
What each workspace does and how they depend on each other.
| Workspace | Kind | Purpose |
|---|---|---|
apps/web (@soma/web) | App | Next.js 15 App Router — the only deployable. Chat, entities, timeline, graph, settings, all API routes. |
apps/bot (@soma/bot) | Lib + dev-only polling | Exports the grammY Bot instance used by apps/web/api/telegram/webhook. pnpm --filter @soma/bot dev runs long polling for local dev (no public URL needed). |
apps/docs (@soma/docs) | App | This site. Astro + Starlight. Deploys to Cloudflare Pages. |
apps/mobile (@soma/mobile) | App | Expo RN + NativeWind (early stub). |
packages/agent (@soma/agent) | Lib | Mastra agents, prompts, memory, Inngest workflow functions, observability. |
packages/tools (@soma/tools) | Lib | The tool registry — memory_*, search_*, graph_*, schedule_*, external/*. |
packages/db (@soma/db) | Lib | Drizzle schema, migrations, RLS SQL, integration tests. |
packages/core (@soma/core) | Lib | Zod schemas for entities, edges, events, facts, sources. |
packages/ui (@soma/ui) | Lib | shadcn primitives, design tokens (dark-first warm amber). |
packages/api-client (@soma/api-client) | Lib | TanStack Query hooks wrapping server actions. |
packages/config (@soma/config) | Lib | Shared tsconfig, ESLint flat configs, Vitest config. |
Dependency graph
flowchart TB
core["@soma/core<br/>zod schemas"]
db["@soma/db<br/>drizzle + rls"]
tools["@soma/tools"]
agent["@soma/agent"]
ui["@soma/ui"]
api["@soma/api-client"]
web["apps/web<br/>(single deployable)"]
bot["apps/bot<br/>(exports bot)"]
core --> db
core --> tools
db --> tools
tools --> agent
agent --> bot
agent --> web
bot --> web
ui --> web
api --> web
core --> uiInvariants
- No workspace imports upward (e.g.
packages/toolsnever importsapps/web). apps/webis the only production deployable.apps/botis simultaneously a workspace library (re-exportingbot) and a dev-only runnable for polling.packages/confighas no siblings that depend on itsdist/— everything consumes the raw.mjs/.jsonfiles via workspace symlinks.