Skip to content

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.

  1. Find the owning capability or document schema.
  2. Update the service or panel that owns the behavior.
  3. Add a meaningful test for the changed contract or failure mode.
  4. Run that workspace’s typecheck and tests.
  5. 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.