Skip to content

ADR-0001: Monorepo structure (backend + frontend + docs)

  • Status: Accepted
  • Date: 2026-06-04
  • Deciders: AOP core

Context

The platform spans a Python backend (orchestrator, RAG, data infrastructure, fine-tuning), a TypeScript/Next.js frontend (Canvas UI), shared data contracts, and operational documentation. These components are developed together, evolve together, and share contracts (the LLM/data schemas the UI consumes). We need a repository layout that keeps them in lockstep without premature service fragmentation.

Decision

Adopt a single monorepo with top-level separation by concern:

backend/    Python package `aop` (installable, versioned) + tests
frontend/   Next.js app (pnpm workspace root for the UI)
docs/       adr/ api/ runbooks/ schemas/   (cross-cutting documentation)
scripts/    bootstrap + maintenance scripts
.github/    CI workflows
docker-compose.yml   local data-infrastructure stack
  • The backend is a proper installable package (pip install -e ./backend) with its own pyproject.toml, so tooling config (ruff, mypy, pytest) is colocated with the code it governs.
  • The frontend is self-contained under frontend/ with its own package.json.
  • CI runs backend and frontend as independent jobs (see .github/workflows/ci.yml).
  • Each module carries its own README.md and CHANGELOG.md; cross-cutting decisions live in docs/.

Consequences

  • Positive: atomic cross-stack changes (e.g. a schema change + its UI consumer) land in one commit; one clone, one CI config, shared docs.
  • Positive: the backend remains independently installable and publishable.
  • Negative: the repo mixes Python and Node toolchains; contributors need both. Mitigated by per-directory CI jobs and the bootstrap scripts.
  • Future: if a component needs independent release cadence, it can be split out later; the package boundary already exists.