Clean Architecture Design
Relevant source files
The following files were used as context for generating this wiki page:
The Memory Context Browser (MCB) follows a strict Clean Architecture design pattern to ensure high performance, maintainability, and clear separation of concerns. The core philosophy centers on an inward-only dependency flow where business logic (the Domain) remains independent of external frameworks, protocols, and infrastructure details.
Compliance with these architectural boundaries is enforced at compile time via workspace crate organization and at development time through the mcb-validate engine. This engine automatically scans the codebase for violations such as circular dependencies, improper layer crossing, or direct instantiation of services instead of using Dependency Injection (DI).
Sources: README.md:95-104, AGENTS.md:258-271, crates/mcb-validate/src/validators/dependency/validator.rs:18-20
Layered Hierarchy and Dependency Flow
MCB is organized into several workspace crates, each representing a specific layer in the Clean Architecture stack. Dependencies must always point toward the center (Domain), and lower-level concrete providers are never imported directly into handlers.
The diagram above illustrates the inward dependency flow where the Domain layer serves as the central point of truth, supported by the Utilities leaf crate.
Layer Descriptions
| Crate | Responsibility | Permitted Internal Dependencies |
|---|---|---|
| mcb-server | MCP protocol implementation, transport (Axum/Stdio), and tool handlers. | mcb-domain, mcb-infrastructure, mcb-utils |
| mcb-infrastructure | DI wiring, configuration, logging, and runtime composition. | mcb-domain, mcb-providers, mcb-utils |
| mcb-providers | Implementations of domain ports (e.g., OpenAI, Milvus, Git). | mcb-domain, mcb-utils |
| mcb-domain | Entities, Value Objects, Port traits, and Domain Errors. | mcb-utils (or zero) |
| mcb-utils | Shared constants, helpers, and leaf utilities. | None (leaf crate) |
Sources: README.md:106-117, AGENTS.md:273-286, config/mcb-validate-internal.toml:17-22
Core Architectural Components
The system relies on several key patterns to maintain the integrity of the Clean Architecture:
Domain Entities and Value Objects
- Entities: Must possess a unique identity field (e.g.,
Uuid). - Value Objects: Must be immutable. Any operation that changes a value must return a new instance rather than mutating
&mut self.
Ports and Adapters
Domain logic interacts with the outside world via Ports (traits defined in mcb-domain). Adapters (implemented in mcb-providers) provide the concrete logic for these ports. Infrastructure wires them together using Dependency Injection.
Dependency Injection (DI)
Direct instantiation of services within handlers is forbidden. Components must be registered via linkme provider descriptors and injected through the application context.
Sources: crates/mcb-validate/src/validators/clean_architecture/violation.rs:18-30, crates/mcb-validate/tests/integration/integration_architecture.rs:114-135
Architecture Validation Rules
The mcb-validate tool enforces specific rules to prevent architectural erosion. Each rule is assigned a unique ID and severity level.
Critical Violation Rules (CA Series)
| Rule ID | Name | Constraint Description |
|---|---|---|
| CA001 | DomainContainsImplementation | Domain layer must only contain traits and types, not logic. |
| CA002 | HandlerCreatesService | Handlers must use DI; they cannot call Service::new(). |
| CA003 | PortMissingComponentDerive | Implementations must be registered in the DI container. |
| CA004 | EntityMissingIdentity | Structs in entities/ must have an id or uuid field. |
| CA005 | ValueObjectMutable | Structs in value_objects/ cannot have &mut self methods. |
| CA006 | ServerImportsProviderDirectly | Server must use infrastructure re-exports, not provider crates. |
| CA009 | InfraImportsApplication | Infrastructure cannot depend on the Application layer (circularity). |
Sources: crates/mcb-validate/src/validators/clean_architecture/violation.rs:32-130, crates/mcb-validate/tests/integration/integration_architecture.rs:13-25
Validation Process Flow
The validation engine utilizes AST (Abstract Syntax Tree) parsing and dependency graph analysis to detect breaches.
The validation process ensures that every commit adheres to the established layer boundaries before being merged.
Sources: crates/mcb-validate/src/validators/dependency/validator.rs:56-65, crates/mcb-validate/tests/integration/integration_architecture.rs:309-325
Conclusion
The Clean Architecture design in MCB provides a robust framework for scaling a complex MCP server with multiple embedding and vector store providers. By strictly isolating the Domain logic and using mcb-validate to enforce these boundaries, the project ensures that infrastructure changes do not leak into business rules, maintaining a stable and testable core.
Sources: README.md:120-125, AGENTS.md:329-335