Project Structure

Relevant source files

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

• Cargo.toml
• crates/sentinel/Cargo.toml
• crates/sentinel/src/lib.rs
• README.md
• IMPLEMENTATION_PLAN.md
• rustfmt.toml
• CODE_OF_CONDUCT.md

The Sentinel project is a document-based Database Management System (DBMS) written in Rust. Its core design principle is "Filesystem is the Database," prioritizing trust, transparency, and compliance by storing all data as files on disk. This structure leverages standard OS-level tooling and security for data management, making every piece of data inspectable and auditable by design.

The project is organized as a Rust workspace, with the main logic encapsulated in the sentinel crate. The structure is planned to evolve through multiple phases, starting with core DBMS functionality and progressively adding features for durability, performance, security, and replication. The detailed architecture and implementation strategy are outlined in the Implementation Plan.

Sources: README.md:10-12, README.md:124-125, IMPLEMENTATION_PLAN.md:13-18, Cargo.toml:1-4

Workspace and Crate Organization

The project is set up as a Rust workspace, which is defined in the root Cargo.toml file. This allows for managing multiple related crates within a single repository.

Sources: Cargo.toml:1-4

[workspace]
resolver = "3"
members = [
    "crates/*"
]

Sources: Cargo.toml:1-4

The primary component is the sentinel crate, located at crates/sentinel. This crate will contain the core logic for the DBMS.

Sources: crates/sentinel/Cargo.toml:2-3

This diagram illustrates the workspace and crate layout.

Architectural Overview

The system is designed with a layered architecture, separating concerns from the client-facing API down to the filesystem interactions.

The following diagram shows the planned core components of the Sentinel system.

The design is based on several key principles:

• Filesystem is the Database: Leverage OS reliability and tooling.
• Immutability by Default: Use append-only logs and soft deletes for a clear audit trail.
• Security First: Employ file permissions, encryption, and cryptographic verification.
• UNIX Philosophy: Do one thing well and compose with standard tools.

Sources: README.md:124-128

Data Storage Model

Sentinel represents database tables as folders and documents as files within those folders. The primary key of a document is its filename. This structure makes the data transparent and accessible with standard command-line tools.

The planned folder structure for a collection is as follows:

Document Format

Each document is a JSON file containing user data and reserved metadata fields prefixed with an underscore (_).

Field	Description
_id	The document's primary key (matches filename).
_ts	Timestamp of the last update.
_v	Version number of the document.
_hash	Cryptographic hash (e.g., SHA-256) for integrity verification.
_sig	Digital signature for tamper detection.

Sources: IMPLEMENTATION_PLAN.md:59-69

Core Component Specifications (Planned)

The IMPLEMENTATION_PLAN.md outlines the key Rust structs that will form the core of the system.

Store and Collection Managers

The Store manages all collections (directories), while the Collection manages documents (files) within a single collection.

This class diagram shows the relationship and key methods of the planned Store and Collection structs.

Dependencies

The project plans to use a set of well-known Rust crates to handle asynchronous operations, serialization, concurrency, and encryption.

Crate	Purpose
tokio	Asynchronous runtime for concurrent I/O.
serde / serde_json	JSON serialization and deserialization.
dashmap	High-performance concurrent hash map for caching.
fs2	Cross-platform file locking.
aes-gcm / chacha20poly1305	Authenticated encryption algorithms.
git2	Bindings for libgit2 to manage Git-based replication.
bincode	Binary serialization for the Write-Ahead Log (WAL).

Sources: IMPLEMENTATION_PLAN.md:96-100, IMPLEMENTATION_PLAN.md:141-144, IMPLEMENTATION_PLAN.md:155-158, IMPLEMENTATION_PLAN.md:170-173, IMPLEMENTATION_PLAN.md:213-218, IMPLEMENTATION_PLAN.md:251-254, IMPLEMENTATION_PLAN.md:465-500

Build Configuration and Tooling

The project is configured for optimized release builds and standardized code formatting.

Release Profile

The root Cargo.toml defines a release profile optimized for performance and small binary size. Key settings include:

• LTO (Link Time Optimization): Enabled for better cross-crate optimizations.
• Panic Strategy: Set to abort to reduce binary size and avoid unwinding overhead.
• Optimization Level: Set to 3 (maximum).
• Symbol Stripping: Enabled to reduce final binary size.

[profile.release]
codegen-units = 1           # Single codegen unit for better optimizations
lto = true                  # Link Time Optimization for better codegen
opt-level = 3               # Max optimization level
panic = "abort"             # Abort on panic, no unwinding, smaller binary and better security
strip = true                # Strip symbols to reduce binary size

Sources: Cargo.toml:11-19

Code Formatting and Linting

• Formatting: The rustfmt.toml file enforces a consistent code style across the project, with max_width = 120.
• Linting: The workspace Cargo.toml defines an extensive set of clippy lints to enforce strict code quality and safety standards. Many lints are set to deny, which will fail the build if violated.

Sources: rustfmt.toml, Cargo.toml:21-421

Summary

The project structure of Sentinel is deliberately simple and transparent, directly reflecting its core philosophy of making the filesystem the database. It is organized as a standard Rust workspace with a phased implementation plan that prioritizes a solid foundation of core DBMS features before moving to advanced capabilities like concurrency, performance optimizations, and distributed replication. The use of configuration files for build optimization (Cargo.toml), code style (rustfmt.toml), and community standards (CODE_OF_CONDUCT.md) establishes a robust framework for development.

Sources: README.md, IMPLEMENTATION_PLAN.md, Cargo.toml, rustfmt.toml, CODE_OF_CONDUCT.md