Skip to main content

​
ADR-0001: Runtime, language, and repository layout

Status: Accepted · 2026-07-14

​
Decision

  • TypeScript everywhere (server, worker, web, shared contracts).
  • Bun 1.3.x as the runtime and toolchain: TS-native execution, built-in bun:sqlite, built-in Jest-compatible test runner, workspace-aware installs.
  • Hono for the HTTP API (TS-first, tiny, runs natively on Bun and Node).
  • Zod for runtime validation of API inputs, config, events, and AI outputs.
  • React + Vite for the web app.
  • Bun workspaces monorepo:
    • packages/shared — types, contracts, event schemas shared by server and web
    • packages/server — API + worker + domain modules + migrations + fixtures + tests
    • packages/web — React UI

​
Context

The dev machine has no Node.js; Bun 1.3.14 is installed. Bun removes two classic sources of setup friction for a credential-free vertical slice: native-module compilation for SQLite drivers and a separate test-runner/transpiler toolchain. One language across API/worker/UI maximizes velocity for a single-session build and keeps contracts shared, not duplicated.

​
Consequences

  • Local development requires Bun (curl -fsSL https://bun.sh/install | bash); the README states the exact version tested.
  • Production evolution path: the server code uses web-standard APIs via Hono and a thin DB layer, so migrating to Node 22 + better-sqlite3/Postgres is mechanical if a customer environment mandates Node. Revisit if Azure deployment tooling (e.g., Functions) forces a Node runtime.
  • No Python/JVM ML stack in the slice; the inference ensemble is TS + provider adapters (see ADR-0005), which matches the mock-first requirement.