ADR-005: Multi-Repo over Monorepo¶
Status: Accepted Date: 2026-03-09
Context¶
Tablez has 11 bounded contexts (services, infrastructure, docs). Need to decide whether to use a single monorepo or separate repositories.
Options Considered¶
| Option | Pros | Cons |
|---|---|---|
| Multi-repo | Independent CI/CD, smaller context for AI agents, clear ownership, independent deploy | Cross-repo changes harder, need shared contracts package |
| Monorepo | Atomic cross-service changes, single CI config, easier refactoring | Large context window for AI, slower CI, harder to scope permissions |
Decision¶
Use multi-repo architecture with 11 separate repositories in the tablez-dev GitHub organization.
Rationale¶
- AI agent productivity. AI coding agents work best with smaller, focused codebases. An agent working on
tablez-reservationonly needs that repo's context — not the entire platform. This reduces token cost and hallucination risk. - Independent deployment. Each service has its own CI/CD pipeline and deploys independently. A change to the notification service doesn't trigger reservation service CI.
- Bounded context enforcement. Multi-repo makes it physically impossible to create cross-service dependencies that bypass the contracts package. The architecture enforces itself.
- Volatility-based gating. High-volatility services (web, gateway) auto-deploy. Low-volatility services (migration) require human gates. This is natural with separate repos and pipelines.
- Shared types via
tablez-contracts. Compile-time type safety across service boundaries without runtime coupling.
Consequences¶
- Cross-service changes require coordinating PRs across repos (contracts first, then consuming services).
- Need a repo manager script or tool to clone/pull/status all repos at once.
tablez-contractsmust be updated carefully — breaking changes affect all services.