# Architecture

`apps/` are runnable surfaces; `packages/` are the shared layers they compose from. This is the code map — read it before exploring code.

```
apps       cli   www   docs   backstage
             │ consume
packages   @arbe/core ⇄ sandbox      teams ──▶ core
             │ composes
           streams ──▶ errors

leaf       cmd   task   agents   skills   style   supabase
```

`cli` runs on bun; `www` is sveltekit on CF Workers; `docs` (`@arbe/www-docs`) is astro/starlight; `backstage` is the durable-workflow and dispatch daemon on Fly (app `arbe-backstage`) — it composes `@arbe/core` and runs the speaker decision and the bot's turn in-process (see [workflows](../workflows.md), [dispatch](chat/dispatch.md)).

## Packages

- `@arbe/core` — the domain hub. Per-entity write modules (houses, agents, environments, threads, entries, configs, workflows, volume, files), the canonical schemas every other layer maps its data into, membership and permission helpers, the pi session adapter, the dispatch tool loop (`dispatch/`), and the director's pure selection rules (`thread-director/`).
- `@arbe/streams` — the durable-stream layer thread entries flow through (client, gateway, server).
- `@arbe/sandbox` — the Daytona sandbox runtime that runs agent work (`src/daytona/`); also the detached coding-agent launcher and in-sandbox runner. Imports `@arbe/core` back for schemas.
- `@arbe/task` — the repo-native task graph in `.arbe/tasks/`.
- `@arbe/errors` — shared error types. Zod-only, so leaf packages can throw canonical errors.
- `@arbe/cmd` — the CLI's command layer: typed command defs, argv parsing over `node:util.parseArgs`, help rendering.
- `@arbe/teams` — resolves a `team.json` from disk, inlining its prompt `$ref`s; holds the bundled teams (kanteen, mull, pingpong).
- `@arbe/agents` — the agent registry: `arbe`, `librarian`, `oracle` — one spec plus markdown body each, which the CLI installs into a harness.
- `@arbe/skills` — the SKILL.md library agents load; the CLI embeds the ones it installs into its compiled binary.
- `@arbe/style` — the CSS tokens and fonts `www` and `www-docs` share.
- `@arbe/supabase` — the production database: migrations, seed, tests, and the generated `database.types.ts`.

## Outside apps/ and packages/

- `supabase/functions/arbe-proxy` — the sandbox-egress shim (a dumb pipe to the CF worker); deployed with the supabase CLI from the repo root. Migrations and `database.types.ts` live in `@arbe/supabase`, not here.
- `tests/` — markdown prompts that drive the real deployed stack, not a unit runner (see `../../tests/README.md`).
- `scripts/` — repo-level maintenance and probe scripts.