Repository guide
| Directory | What belongs here |
|---|---|
apps/mainframe/ |
Core HTTP/WS service, persistence, auth, tasking, media indexes, and data tools |
apps/web/ |
Terminal panels, workspace state, and browser interactions |
services/ |
Independently launched modules |
packages/schema/ |
Shared Zod schemas, capabilities, protocol frames, and constants |
packages/client/ |
Terminal and consuming-module SDK |
packages/provider/ |
Provider SDK, contract harness, and backend metrics registry |
packages/sim/ |
Simulator engine, world types, and camera renderer |
packages/ui/ |
Shared components, IBM Plex fonts, and theme tokens |
deploy/ |
Compose, Caddy, monitoring, environment examples, and launcher |
docs/ |
This Astro/Starlight site |
dev-docs/ |
Internal plans, decisions, audits, and historical evidence |
The workspaces export TypeScript sources directly. Bun runs backend code, and Vite builds the frontend. Keep imports through a package’s public exports rather than reaching into another workspace’s source directory.
Boundary checks prevent the frontend from importing backends or the simulator, prevent modules from importing other services or apps, and prevent packages from importing applications. A module needing another service’s information should consume an explicit API or shared schema.
A typical change
Section titled “A typical change”- Find the owning capability or document schema.
- Update the service or panel that owns the behavior.
- Add a meaningful test for the changed contract or failure mode.
- Run that workspace’s typecheck and tests.
- Run
bun run check. For an interface change, also run the browser smoke suite against a running stack.
Database migrations live in apps/mainframe/drizzle/. Generate a migration with bun run --cwd apps/mainframe db:generate, review the SQL, and apply it with db:migrate. The deployed Core image runs migrations before starting. Take a backup before deploying a migration that changes stored data.
Build documentation with bun run docs:build. Cloudflare Pages builds and publishes docs/dist at https://docs.terminal.dev.mainline.inc/ on pushes to main.