Skip to content

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

Home › Reference › Eac › Architecture › Decisions › Dr005

Status

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

Context

Repository contains many 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/cli/eac
    patterns:
      source: ["**/*.go"]
      tests: ["**/*_test.go"]
  gherkin:
    root: specs/eac-commands
    patterns:
      source: ["**/*.feature"]

Component Kinds: Many kinds (go, typescript, dockerfile, book, workflows, gherkin, structurizr, bash, pwsh, markdown, json, yaml) defined in contracts/core/0.1.0/schemas/defaults/blueprints.yml under component-kinds section

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: .eac/repository.yml with modules forming a dependency graph

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

  1. Flat Directory Structure: Rejected - no clear boundaries, scales poorly, ownership ambiguity
  2. Package Managers Only: Rejected - doesn't handle containers/docs/workflows, no cross-language support
  3. 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.