Skip to main content

Architecture Decision Records

ADRs document significant architectural decisions, their context, and consequences. They are living documents stored in .context/decisions/ and synced here by CI.

info

ADRs are never deleted. Superseded decisions get status: superseded with a pointer to the replacement. The full history is preserved.

All decisions​

ADR-001accepted

Single monorepo over multi-repo

All code (backend, frontend, ML, infra, docs) lives in a single monorepo.

Enables atomic cross-cutting changes and shared tooling for AI agents.

2026-03-15
ADR-002accepted

Bazel with staged adoption

Use Bazel as the unified build system, adopting incrementally per platform.

Hermetic builds critical for agent reproducibility. Staged to avoid blocking early development.

2026-03-15
ADR-003accepted

Monolith-first backend

Start with a single Kotlin/JVM service using interface+adapter pattern for future extraction.

Reduces ops overhead. Interface boundaries preserve microservice extraction path.

2026-03-15
ADR-004accepted

ML as top-level workspace

ML code lives at ml/ as a standalone Python workspace, not embedded in the backend.

Python and JVM have incompatible toolchains. API-only coupling keeps integration clean.

2026-03-15
ADR-005accepted

PostgreSQL+JSONB for Knowledge Graph

Use PostgreSQL with JSONB columns instead of a dedicated graph database (Neo4j).

Simpler ops for fewer than 20 customers. JSONB handles schema evolution. Migration to Neo4j remains possible.

2026-03-15
ADR-006accepted

Task files + cascading context

Use .tasks/ directories and 3-level cascading context (L1/L2/L3) for agent work.

Minimizes token usage per agent session while ensuring correct context is always loaded.

2026-03-15
ADR-007accepted

public/ for publishable packages

Customer-facing CLI and packages live in public/ directory, separate from internal code.

Clear boundary between what ships to customers and what stays internal.

2026-03-15

Process​

To propose a new ADR:

  1. Copy .context/decisions/TEMPLATE.md to .context/decisions/ADR-NNN-slug.md
  2. Fill in context, decision, alternatives, and consequences
  3. Submit a PR — discussion happens in the review
  4. After acceptance, CI syncs the ADR to this docs site

See the spec-driven development workflow for how ADRs fit into the broader development process.