Repositories and Modules

Repository and Module Organization

Repository as Domain Boundary

A repository represents a cohesive domain of functionality, following the Single Responsibility Principle at the architectural level. The repository boundary defines what concerns belong together from a business or technical perspective. This domain focus provides clear ownership and makes the codebase navigable.

Multi-Module Structure

Within a repository, modules partition functionality into logical units while remaining within the repository's domain scope. Each module:

• Addresses a specific aspect of the domain (e.g., API layer, core logic, persistence, UX)
• Maintains its own clear functionality/responsibility without overlapping concerns with sibling modules

Lifecycle Independence

Repositories maintain separate lifecycles, meaning:

• Each repo can evolve at its own pace based on domain needs
• Can be versioned and released independently if needed
• Repo Lifecycle gets applied to all modules within repo
• Teams can work with different release cadences
• Breaking changes are mostly managed at repository boundaries, not internal module boundaries

Example Structure

embabel-agent/              # Domain: Agent oframework
├── embabel-agent-api/      # Module: Public and Internal API contracts
├── embabel-agent-shell/    # Module: Shell infrastructure and commands 
└── embabel-agent-starters/ # Module: Dependencies in order to bootstrap configurable functionality, such as models

This approach balances modularity with cohesion - keeping related concerns together while maintaining clean internal separation.

Common Repo

Envision that common utilities / frameworks can be shared cross multiple repos with independent lifecycle management.

       common 
       |   common-0.1.6
       |---------------agent 0.2.0
       |   common-0.1.5
       |---------------rag   0.0.1