Skip to content

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

Home › Reference › Eac › Architecture › Decisions › Dr001

Status

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

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)
│   └── clie/cli/                  # CLIE CLI
├── typescript/vscode-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 and AI prompt templates
├── .clie/                         # CLIE configuration
├── .claude/                      # Claude Code agents, commands, skills
└── .github/                      # CI/CD workflows and actions

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

Component Types: Many 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.