ADR-001: Single monorepo over multi-repo
Context
Aucert is a polyglot platform (Kotlin backend, TypeScript frontend, Python ML, Protobuf schemas, Terraform infrastructure). We needed to choose between a single monorepo or multiple repositories per platform.
A key factor is that Aucert relies heavily on AI agents for development. Agents need full codebase context to make informed decisions — understanding how a backend API change affects the frontend, how proto schema changes propagate, and how infrastructure relates to application code.
The cascading context system (L1/L2/L3 context files in .context/) works because all context files are co-located in one repository, loadable by any agent regardless of which platform they're working on.
Decision
Use a single monorepo for all platforms, infrastructure, and documentation. All code, schemas, configs, and context files live in one repository.
Alternatives considered
| Option | Pros | Cons |
|---|---|---|
| Monorepo (chosen) | Full agent context, atomic cross-platform PRs, single CI, shared tooling | Larger clone, need polyglot build system |
| Multi-repo (per platform) | Smaller repos, independent versioning, platform-specific CI | Agents lose cross-platform context, coordinated changes require multi-repo PRs, duplicated CI config |
| Multi-repo + shared proto | Shared contract repo, independent deployment | Still fragmented context, proto version sync overhead |
Consequences
What becomes easier
- AI agents can see the full codebase and make cross-cutting changes
- Protobuf schema changes + generated code + consuming code ship in one PR
- Context files (
ARCHITECTURE.md,CONVENTIONS.md) apply globally - CI runs affected tests automatically via path-based filtering
What becomes harder
- Repository grows larger over time (mitigated by sparse checkouts)
- Need a polyglot build system (Bazel — see ADR-002)
- CODEOWNERS becomes essential to prevent accidental cross-platform reviews