Repository guide
| Directory | What belongs here |
|---|---|
apps/mainframe/ |
Core HTTP/WS service, persistence, auth, tasking, media indexes, and data tools; the code of the optional packages in src/packages/{drones,air-picture,comms,simulation}/ |
apps/web/ |
Terminal panels, workspace state, and browser interactions; the UI of the optional packages in src/packages/{drones,air-picture,comms}/ |
apps/sim-ui/ |
The simulator’s own page |
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 |
packages/cot/ |
The CoT event codec, shared by TAK and Air Picture |
packages/surveillance/, packages/surveillance-native/ |
Air Picture’s fusion engine and its Rust core |
packages/autel-protocol/, packages/generic-drone-protocol/ |
Drone protocol layers shared by the Drones modules |
deploy/ |
Compose, Caddy, monitoring, the launcher, and one installation config per host in deploy/installations/ |
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.
The same checks keep the optional Mainline Packages apart. Base code in either app never imports a package directory, and one package never imports another. Mainframe builds the installed packages in one place (apps/mainframe/src/index.ts); a package reaches Base code through a port that Base declares. In Terminal, a package registers itself in apps/web/src/packages/<id>/index.ts and hands its panels, menu rows, settings sections, map layers and chips to the Base shell through the named contribution points of apps/web/src/app/contributions.ts. A Mainframe without that package never loads its UI chunk.
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.