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 |
apps/front/ |
Front Android app (inc.mainline.front), built independently with its Gradle wrapper; native backend integration is planned |
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.
The database schema lives in apps/mainframe/drizzle/ as a single migration for an empty database. After changing src/db/schema.ts, delete the folder’s SQL and meta/ and regenerate it with bun run --cwd apps/mainframe db:generate --name init; apply it to a fresh database with db:migrate (the development database is reset with bun dev:infra reset). Deployments start from an empty database; there is no upgrade path that preserves 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.