Database Schema & SeaORM
Relevant source files
The following files were used as context for generating this wiki page:
The Memory Context Browser (MCB) utilizes SeaORM as its primary Object-Relational Mapping (ORM) framework to manage persistent data across various database backends. The architecture follows Clean Architecture principles, where the database layer acts as a provider that implements ports defined in the domain layer. This ensures that the core business logic remains decoupled from the specific database implementation, allowing for flexibility and testability.
The system is designed to support both SQLite and PostgreSQL through SeaORM's async runtime. The database schema encompasses a wide range of entities including project management components (phases, issues, decisions), agent session tracking, and organizational structures. These entities are managed through a centralized repository pattern, utilizing generic CRUD macros to ensure consistency and reduce boilerplate.
Sources: Cargo.toml:405-420, crates/mcb-providers/src/database/seaorm/repos/project.rs:1-15
Architecture and Integration
The database layer is integrated into the workspace through the mcb-providers crate. It leverages the SeaQL ecosystem, specifically pinning versions for SeaORM, SeaORM Migration, SeaQuery, and Seaography to ensure stability.
Component Relationship
The following diagram illustrates the relationship between the domain ports and the SeaORM-backed provider implementation.
The diagram shows how the SeaOrmProjectRepository bridges the domain's requirements with the concrete SeaORM implementation and database connection.
Sources: crates/mcb-providers/src/database/seaorm/repos/project.rs:271-275, crates/mcb-providers/Cargo.toml:132-136
Entity Definitions
The project defines a comprehensive set of entities managed by SeaORM. These entities are organized into modules and registered for GraphQL schema generation via Seaography.
Primary Entities
The core entities are exposed through a prelude and summarized in the table below:
| Entity Category | Modules | Description |
|---|---|---|
| Project Management | projects, project_phases, project_issues, project_decisions | Handles the structural hierarchy of code projects and tasks. |
| Agent & Session | agent_sessions, tool_calls, observations | Tracks AI agent interactions, session history, and external tool usage. |
| Identity & Access | organizations, users, api_keys, teams | Manages multi-tenancy, user authentication, and permissions. |
| VCS & Indexing | repositories, branches, file_hashes, index_operations | Manages repository metadata and semantic search indexing status. |
Sources: crates/mcb-providers/src/database/seaorm/entities/mod.rs:7-60
Project Schema Detail
The project family of entities supports complex relationships such as dependency traversal and filtering.
This ER diagram shows the ownership and operational relationships between project-related entities.
Sources: crates/mcb-providers/src/database/seaorm/repos/project.rs:70-200
Repository Implementation
MCB employs a highly macro-driven approach to implement repositories. This pattern, found in common.rs, provides a standard way to handle CRUD operations while mapping DbErr to domain-specific Error types.
Generic CRUD Macros
Key macros used to implement the ProjectRepository and other storage traits include:
sea_repo_insert!: Converts domain types to ActiveModels and persists them.sea_repo_get!: Retrieves entities by primary key, returning a "Not Found" error if missing.sea_repo_get_filtered!: Scopes queries by additional columns (e.g.,org_id).sea_repo_list!: Fetches collections with optional filtering.sea_repo_delete!: Removes records by primary key.
Sources: crates/mcb-providers/src/database/seaorm/repos/common.rs:100-200
Trait Implementation Example: Project Repository
The SeaOrmProjectRepository uses the sea_pub_crud! and sea_pub_crud_scoped! macros to generate methods for phases and issues directly on the struct.
// Example of macro usage for project phases
sea_pub_crud!(SeaOrmProjectRepository {
db_field: db,
entity: project_phase,
domain: ProjectPhase,
label: "ProjectPhase",
create: create_phase(phase),
get: get_phase_by_id(id),
update: update_phase(phase),
delete: delete_phase(id),
});
Sources: crates/mcb-providers/src/database/seaorm/repos/project.rs:35-43
Data Access Patterns
Scoped Operations
Multi-tenancy is enforced via org_id scoping. Repositories verify project ownership before performing operations on related entities like issues or decisions.
The sequence diagram demonstrates the validation step required to ensure data isolation between organizations.
Sources: crates/mcb-providers/src/database/seaorm/repos/project.rs:88-105
Dependency Traversal
The repository implements specialized logic for traversing issue dependencies breadth-first. This is used to understand task impact and prerequisite chains up to a specified max_depth.
Sources: crates/mcb-providers/src/database/seaorm/repos/project.rs:186-215
Conclusion
The SeaORM integration in MCB provides a robust, type-safe, and asynchronous data layer. By utilizing a combination of generated entities, shared CRUD macros, and strict architectural boundaries, the project maintains a high degree of maintainability. This structure supports complex features like multi-tenant project management and dependency tracking while remaining compatible with multiple SQL backends.
Sources: crates/mcb-providers/src/database/seaorm/repos/project.rs:271-380, crates/mcb-providers/src/database/seaorm/repos/common.rs:1-15