Layer 05 · Repository map
Repository map
One Bun monorepo holds everything: four deployable programs, three shared packages, and the definitions of the stores they run against. This is the layer where the concepts from the earlier pages get an address.
Major folders and what each one encapsulates
| Path | Domain concern |
|---|---|
cli/ | The command-line tool and TUI: agent adapters (one per coding agent), local SQLite event store and indexer, share/sync client, git and agent hooks, release tooling. |
api/ | The backend: self-hosted Convex functions, the /v1 HTTP REST API, auth and policies, the dual-write service layer to Tinybird, crons, the analysis outbox/worker, migrations, seeds, and the Docker compose stack for Postgres + backend. |
frontend/ | The web app: Next.js App Router pages (catalog, profiles, trace viewer, settings, docs), the server-only data layer, same-origin API proxies, and the assistant chat UI. |
agent/ | The assistant service: a Hono HTTP server running the Flue agent runtime, trace tools (search/list/show via the API, lookups via direct SQL), streaming chat, and write-behind conversation persistence. |
packages/shared/ | @traces/shared: the cross-program type contract — trace/message/part models, API types generated from OpenAPI, typed Convex function references, Tinybird row types, and their generators. |
packages/ai/ | @traces/ai: the AI-analysis data product — prompt program, input selection, output schema, and the deterministic fallback. |
packages/launcher/ | @traces/launcher: opens commands in a new terminal window per platform; used by the CLI's resume feature. |
tinybird/ | The analytics store as code: datasource schemas, pipes (SQL endpoints), fixtures, tests, and local/backup tooling. |
cache/ | The shared cache deployment: Valkey fronted by the webdis HTTP gateway, plus the script that wires it into the backend. |
observability/ | Telemetry plumbing: OpenTelemetry collector configs (including the SigNoz gateway) and translators that adapt Convex logs/metrics. |
data/ | Captured real agent session files (per agent) plus scenario fixtures — shared test and seed material for adapters and the backend. |
docs/ | Architecture references and per-project design documents kept alongside the code. |
scripts/ | Repo-level operations scripts: the dev orchestrator, worktree helpers, reset tooling. |
skills/ | The installable "share to Traces" skill content that traces setup writes into coding agents. |
okf/ | A curated, structured knowledge folder about the system itself, aimed at machine readers. |
Entry points worth opening first
| Boundary | Where |
|---|---|
| Database schema (the domain's source of truth) | api/convex/schema.ts |
| Every HTTP route the platform exposes | api/convex/http.ts → api/convex/http/v1/ |
| Scheduled work (crons) | api/convex/crons.ts |
| The dual-write rule between the two stores | api/convex/services/traces.ts with api/convex/lib/tinybird.ts |
| CLI process entry and command tree | cli/src/index.ts, cli/src/commands/ |
| The adapter contract all agents implement | cli/src/adapters/adapter.ts |
| Assistant service entry | agent/src/server.ts |
| Web app routes | frontend/app/ |
How the packages depend on each other
One shared type package fans out to every program; the AI package is consumed
only by the backend; the launcher only by the CLI. Nothing depends on the
deployable programs themselves — all coupling flows through
@traces/shared or through HTTP at runtime.
flowchart TD SHARED["@traces/shared
types + generated contracts"] AI["@traces/ai
analysis program"] LAUNCH["@traces/launcher
terminal launcher"] CLI["@traces/cli
deployable: CLI + TUI"] API["api
deployable: Convex backend"] FE["frontend
deployable: Next.js web app"] AGENT["@traces/agent
deployable: assistant service"] TB[(Tinybird project
datasources + pipes)] CACHE[(Valkey + webdis)] CLI -- "message/part types, API client types" --> SHARED CLI -- "resume in a new terminal" --> LAUNCH API -- "domain types, generated API + Tinybird types" --> SHARED API -- "runs the analysis program" --> AI FE -- "API + assistant types" --> SHARED AGENT -- "session + tool contracts" --> SHARED AI -- "analysis schema types" --> SHARED API -. "pushes events, queries pipes" .-> TB API -. "caches via HTTP" .-> CACHE
Solid arrows are build-time package dependencies (from workspace manifests);
dotted arrows are runtime couplings to the stores defined in this repo. The
CLI and the web app never import each other's code, and the backend's public
contract reaches the other programs only as generated types — which is why
regenerating @traces/shared is the required ritual after changing
an API shape.
Technology stack
| Layer | Technology | Grounded in |
|---|---|---|
| Monorepo & runtime | Bun workspaces, TypeScript 6, Biome for format/lint | package.json, biome.json |
| Backend | Self-hosted Convex 1.42 (backend pinned by image digest) on Postgres 18; migrations, rate-limiter, and workpool components | api/package.json, api/docker-compose.yml, api/convex/convex.config.ts |
| Analytics store | Tinybird (ClickHouse, ReplacingMergeTree tables), local dev via Tinybird Local | tinybird/datasources/, tinybird/package.json |
| Cache | Valkey behind webdis (HTTP) | cache/docker-compose.yml |
| Web app | Next.js 16, React 19, Tailwind CSS v4, Radix UI, Fumadocs, Sentry, Vercel analytics | frontend/package.json |
| CLI | Bun, OpenTUI + Solid.js for the TUI, SQLite for local storage, compiled binaries via npm and Homebrew | cli/package.json, cli/scripts/ |
| Assistant service | Bun + Hono, Flue agent runtime, Vercel AI SDK, Slonik/pg for direct SQL, OpenTelemetry, Sentry | agent/package.json |
| LLM access | Vercel AI SDK and Ax against OpenAI/Anthropic-compatible endpoints | agent/package.json, packages/ai/package.json |
| External integrations | GitHub OAuth + GitHub App, Google OIDC, Hugging Face hub, models.dev, SigNoz via OpenTelemetry collectors | api/convex/services/oauth/, api/convex/internal/github.ts, observability/ |