ADR 0005 — Monorepo with service isolation

ADR 0005 — Monorepo with service isolation

Status: Accepted
Date: 2026-05-05

Context

Five services (substrate, runtime, api, viewer, plus shared lib). Polyglot (Python + TypeScript). Single team. Stack runs as one docker-compose locally.

Decision

Single git repository (manthan/) containing all services side by side under services/, plus shared Python lib at shared/manthan_common/ and shared infra at infra/.

Each service:

• Has its own pyproject.toml (Python services) or package.json (viewer).
• Has its own Dockerfile rooted at the repo so it can COPY from shared/.
• Has its own tests/ directory.
• Is a buildable unit — can be CI-checked, tagged, deployed independently.

A root pyproject.toml defines the dev tool config (ruff, mypy, pytest defaults) shared across Python services.

Consequences

• Atomic cross-service changes. Schema bump in substrate + caller bump in runtime ship in one commit; no inter-repo dance.
• Shared lib is real. manthan_common carries logging, settings, budget guards, type stubs. Single source of truth.
• CI runs per-service. Path-filtered builds keep PR feedback fast.
• Independence from maestro-platform is preserved at the repo boundary, not at the service boundary. The line that matters is manthan/ ↔ maestro-platform/.

Alternatives considered

• Polyrepo (one repo per service). Heavier coordination cost for a five-service v0; deferred.
• Manthan as a subdirectory of maestro-platform. Rejected: violates the totally-independent principle.
• uv workspaces at the root. Considered. Shipping per-service pyproject.toml for now (simpler Dockerfiles, no workspace surprises in CI). Workspace overlay can be added later without breaking individual service builds.