Relational Database Schema
Relevant source files
The following files were used as context for generating this wiki page:
The MCB project utilizes a relational database as a core component of its multi-provider architecture for persistent memory, semantic code search, and codebase understanding. The schema is primarily managed through the SeaORM ecosystem, providing an entity-first approach with support for both SQLite and PostgreSQL backends.
This system facilitates the storage of cross-session observations, project planning entities, and agent activity logs. The database layer is integrated into the project's Clean Architecture as part of the mcb-providers crate, implementing domain ports through repositories like SeaOrmProjectRepository.
Sources: README.md:12-14, crates/mcb-infrastructure/Cargo.toml:88-92, crates/mcb-providers/src/database/seaorm/repos/project.rs:20-22
Core Entities and Data Models
The relational schema is defined by SeaORM entities which represent the physical table structures. Each entity model typically includes an id, organizational context via org_id, and standard timestamps for tracking creation and updates.
Project Entity
The projects table serves as the root container for repository context and planning.
| Field | Type | Description |
|---|---|---|
id | Text (PK) | Unique identifier for the project. |
org_id | Text | Reference to the owning organization. |
name | Text | Human-readable name of the project. |
path | Text | Filesystem path to the project root. |
created_at | i64 | Epoch timestamp of creation. |
updated_at | i64 | Epoch timestamp of last update. |
Sources: crates/mcb-providers/src/database/seaorm/entities/projects.rs:10-25, config/conversions.toml:44-48
Relationship Hierarchy
The schema organizes data into a hierarchy where projects, issues, phases, and decisions are interlinked to support agent workflows.
The diagram shows the logical relationships between project planning entities.
Sources: crates/mcb-providers/src/database/seaorm/repos/project.rs:32-130, config/conversions.toml:44-120
Project Planning and Management
The schema includes dedicated tables for managing the lifecycle of software projects, including phases, issues, and dependencies.
Project Issues and Dependencies
Issues are scoped to organizations and projects. They support complex metadata including issue_type, status, and priority. Dependencies between issues are stored as directed edges in the project_dependency table.
- Issue Filter Logic: The system supports rich querying of issues through
IssueFilter, allowing filtering by status, priority, assignee, and labels (stored as JSON patterns). - Dependency Traversal: The repository implements breadth-first search (BFS) for traversing dependency graphs up to a defined
max_depth.
Sources: crates/mcb-providers/src/database/seaorm/repos/project.rs:100-112, crates/mcb-providers/src/database/seaorm/repos/project.rs:166-180
Conversion Mapping
To maintain Clean Architecture boundaries, the project uses a mapping configuration to convert between database Models (SeaORM) and Domain Entities.
[project_issue]
domain = "ProjectIssue"
import = "mcb_domain::entities::ProjectIssue"
extra_imports = ["mcb_domain::entities::project::{IssueStatus, IssueType}"]
entity = "project_issue"
fields = ["id", "org_id", "project_id", "created_by", "phase_id", "title", "description", "assignee", "estimated_minutes", "actual_minutes", "notes", "design", "parent_issue_id", "created_at", "updated_at", "closed_at", "closed_reason"]
[project_issue.convert.issue_type]
type = "enum"
enum_type = "IssueType"
default = "IssueType::Task"
Sources: config/conversions.toml:210-220
Persistence Mechanisms
MCB leverages specific SeaORM features to handle data flow and synchronization:
- Repository Pattern:
SeaOrmProjectRepositoryencapsulates database interactions, providing a clean API for domain logic. - Entity Registry: Entities are registered for GraphQL schema generation via
seaographyand schema synchronization. - JSON Storage: Complex fields like
metadata,tags, andsettings_jsonare stored as Text/String in the database and deserialized into JSON objects or arrays in the domain layer.
Sources: crates/mcb-providers/src/database/seaorm/repos/project.rs:20-25, config/conversions.toml:8-25, crates/mcb-infrastructure/Cargo.toml:88-95
Summary
The Relational Database Schema in MCB provides a structured foundation for agent memory and project management. By combining SeaORM's type-safe entities with flexible JSON storage and a robust conversion system, the project ensures data integrity while adhering to Clean Architecture principles.