Clean Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• AGENTS.md
• crates/mcb-validate/src/validators/clean_architecture/violation.rs
• config/mcb-validate-internal.toml
• crates/mcb-utils/src/constants/validate/architecture.rs
• crates/mcb-validate/tests/integration/integration_architecture.rs

MCB (Memory Context Browser) implements a strict Clean Architecture pattern to ensure high maintainability, testability, and independence from external frameworks. The system is organized into concentric layers where dependencies flow exclusively inward toward the core domain. This design ensures that business logic remains decoupled from delivery mechanisms (like the MCP protocol) and infrastructure details (such as specific vector stores or embedding providers).

Sources: README.md:105-107, AGENTS.md:144-145, crates/mcb-validate/src/validators/clean_architecture/violation.rs:7-13

Layered Structure and Dependency Flow

The architecture is composed of distinct crates that enforce layer boundaries at compile time. The core principle is that inner layers (Domain) have zero knowledge of outer layers (Infrastructure, Server).

Dependency Hierarchy

The following diagram illustrates the strict inward-only dependency flow utilized in the project:

The hierarchy ensures that mcb-domain remains a leaf node with zero internal dependencies, while mcb-server acts as the entry point facade.

Sources: README.md:110-120, AGENTS.md:148-164, config/mcb-validate-internal.toml:19-24

Crate Roles and Responsibilities

Crate	Layer	Responsibility
mcb-server	Entrypoint	MCP protocol implementation, Axum HTTP handlers, and admin UI.
mcb-infrastructure	Framework	Dependency Injection (DI) wiring via linkme, configuration, and logging.
mcb-providers	Adapters	Concrete implementations of domain ports (e.g., OpenAI, Milvus, Git).
mcb-domain	Core	Entities, value objects, port traits (interfaces), and domain errors.
mcb-utils	Support	Shared constants, helpers, and leaf utilities.

Sources: README.md:110-120, AGENTS.md:148-160, crates/mcb-utils/src/constants/validate/architecture.rs:1-60

Architectural Constraints and Validation

The project utilizes mcb-validate to mechanically enforce Clean Architecture rules. These rules prevent common architectural "leakage" where infrastructure details bleed into the business logic.

Enforcement Rules (Violations)

The validation engine checks for specific anti-patterns, categorized by unique identifiers:

• CA001 (Domain Contains Implementation): Prevents implementation logic from residing in the domain layer. The domain should only contain traits and data structures.
• CA002 (Handler Creates Service): Handlers in the server layer must use constructor injection rather than instantiating services directly.
• CA004 (Entity Missing Identity): Entities must have unique identity fields (e.g., Uuid).
• CA005 (Value Object Mutability): Value objects must be immutable; any "modifying" method must return a new instance.
• CA006 (Direct Provider Imports): The server layer is forbidden from importing mcb-providers directly; it must go through mcb-infrastructure re-exports.

Sources: crates/mcb-validate/src/validators/clean_architecture/violation.rs:20-80, crates/mcb-validate/tests/integration/integration_architecture.rs:18-25

Dependency Injection (DI) Pattern

MCB uses the Port and Adapter pattern combined with the linkme crate for zero-runtime overhead provider registration.

This flow ensures that the Handler only knows about the Trait (Port) defined in the Domain, while the actual implementation (Adapter) is injected by Infrastructure.

Sources: README.md:121-123, AGENTS.md:165-168, crates/mcb-validate/src/validators/clean_architecture/violation.rs:43-50

Implementation Standards

To maintain the architectural integrity, specific implementation rules are followed across the codebase:

• Surgical Edits: Changes must be scoped and reuse existing macros like tool_action! or register_tool!.
• Error Handling: Use Error constructors and Result aliases from mcb-domain. Production code paths must never use unwrap(), expect(), or panic!.
• Naming Conventions: Layers are identified by specific path fragments:
  • /domain/ for core logic.
  • /ports/providers/ for interface definitions.
  • /adapters/ or _impl suffixes for infrastructure implementations.

Sources: AGENTS.md:214-222, crates/mcb-utils/src/constants/validate/architecture.rs:6-50, crates/mcb-validate/tests/integration/integration_architecture.rs:280-320

Summary

The Clean Architecture implementation in MCB provides a robust framework for an MCP server by isolating volatile technical details (like AI provider APIs) from the stable business logic of memory management and code analysis. By utilizing automated validation via mcb-validate, the project ensures that the inward-only dependency flow remains intact as the codebase grows.