Skip to content

DR-001: Use Mono-Repository Layout (Single-Repository Type)

Home › Reference › Decision Records › Dr001

Status

  • [x] Accepted
  • [ ] Proposed
  • [ ] Rejected
  • [ ] Deprecated
  • [ ] Superseded

Date: 2025-11-03

Context

Platform has CLI, VSCode extension, MCP servers, docs, automation, and contracts. Needs coordinated development, atomic commits, code sharing, and independent module versioning.

Problem: How to organize codebase for maintainability and velocity?

Decision

Mono-repository with clear module boundaries and component-based organization.

Structure:

eac/                              # Repository root
├── go/                           # Go workspace
│   ├── eac/                      # EAC namespace (commands, core, mcp, specs)
│   └── r2r/cli/                  # R2R CLI
├── typescript/vscode-ext-commit/ # VSCode extension
├── scripts/                      # Multi-language scripts (pwsh/, sh/)
├── containers/                   # Docker container definitions
├── docs/                         # Documentation (MkDocs)
├── contracts/                    # YAML/JSON schemas and defaults
├── specs/                        # Gherkin specifications
├── release/                      # Changelogs and release notes
├── templates/                    # Project templates
├── .r2r/                         # R2R configuration
├── .claude/                      # Claude Code agents and commands
└── .github/workflows/            # CI/CD workflows

Module Contracts: 21 modules defined in .r2r/eac/repository.yml with YAML contracts specifying components, dependencies, and versioning (e.g., eac-core, eac-commands, r2r-cli, ext-eac, docs, books)

Component Types: 15+ types (go, typescript, dockerfile, book, workflows, gherkin, structurizr, etc.) enable multi-language support within single modules

Versioning: Mixed schemes per module type - SemVer (code), CalVer (docs), Implicit (internal libs). See DR-002 and DR-011 for details.

Consequences

Positive: Atomic commits, simplified dependencies, easy code sharing, unified tooling, single clone, component-based organization enables mixed language support, module contracts provide validation and automation

Negative: Larger repo, build complexity, no per-module access control, merge conflict potential, contract maintenance overhead

Alternatives Considered

  1. Multi-Repository: Rejected - tight coupling makes cross-repo coordination costly
  2. Git Submodules: Rejected - adds complexity without enough benefits
  3. Workspaces Only: Rejected - limited to one language, codebase is multi-language

Tutorials | How-to Guides | Explanation | Reference

You are here: Reference — information-oriented technical descriptions of the system.