DR-005: Modular Monorepo Architecture with Component-Level Contracts

Status

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

Date: 2024-11-15

Context

Repository contains 21 modules (Go libraries, CLI tools, Docker containers, documentation, CI/CD workflows) that need coordinated development, independent versioning, clear ownership boundaries, and automated validation.

Problem: How to organize a multi-language, multi-artifact system with clear boundaries and automation?

Decision

Modular monorepo with YAML-based module contracts defining components, dependencies, versioning, and file ownership.

Module Contract Structure:

moniker: eac-commands
name: Go Commands Library
description: Go library containing CLI command implementations
depends_on: [eac-core]
versioning:
  scheme: SemVer
components:
  go:
    root: go/eac/commands
    patterns:
      source: ["**/*.go"]
      tests: ["**/*_test.go"]
  gherkin:
    root: specs/eac-commands
    patterns:
      source: ["**/*.feature"]

Component Types: 15+ types (go, typescript, dockerfile, book, workflows, gherkin, structurizr, bash, pwsh, markdown, json, yaml) defined in contracts/eac-core/0.1.0/defaults/component-types.yml

Key Capabilities: - Per-module CI/CD workflows - Dependency-aware build orchestration - File ownership validation (no file owned by multiple modules) - Automatic change detection

Module Registry: .r2r/eac/repository.yml with 21 modules forming dependency graph (max depth: 4, max dependents: 5)

Consequences

Positive: Clear boundaries, independent releases, automated validation, multi-language support, dependency tracking, scalable CI/CD, enforced ownership

Negative: Contract maintenance overhead, learning curve, validation complexity

Alternatives Considered

Flat Directory Structure: Rejected - no clear boundaries, scales poorly, ownership ambiguity
Package Managers Only: Rejected - doesn't handle containers/docs/workflows, no cross-language support
Git Submodules: Rejected - coordination overhead, poor developer experience, atomic commits difficult

Tutorials | How-to Guides | Explanation | Reference

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