Home

Relevant source files

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

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

Cyberpath Sentinel is a document-based Database Management System (DBMS) written in Rust. It is uniquely designed to prioritize trust, transparency, and compliance by storing all data as files on disk. In Sentinel, tables are represented by folders, and each document's primary key corresponds to its filename. This approach ensures that every piece of data is inspectable, auditable, and compliant by design, leveraging the underlying filesystem for its core operations.

The project positions itself not as a replacement for high-throughput databases like PostgreSQL or MongoDB, but as a specialized solution for use cases where auditability and security are paramount. These include audit logs, certificate management, compliance rule storage, and encryption key management. It is built for edge devices, disconnected systems, and zero-trust infrastructures where data transparency is critical.

Sources: README.md:7-10, 14-15, IMPLEMENTATION_PLAN.md:12-14

Core Principles

Sentinel's architecture is founded on a set of key design principles that differentiate it from traditional database systems.

1. Filesystem is the Database: It leverages the reliability, maturity, and rich tooling of modern operating system filesystems.
2. Immutability by Default: Operations favor append-only logs and soft deletes, preserving a complete audit trail.
3. Security First: Security is built-in through file permissions, encryption, and cryptographic verification.
4. UNIX Philosophy: It aims to do one thing well (transparent data storage) and composes easily with standard tools like grep, rsync, and git.
5. Zero External Dependencies: The core system is designed to work offline and on edge devices without requiring external services.

Sources: README.md:121-127

Architecture

The system is designed as a layered architecture, with a client library at the top and the filesystem at the bottom.

Sources: IMPLEMENTATION_PLAN.md:21-22, README.md:129-142

System Design

The following diagram illustrates the high-level components of Cyberpath Sentinel.

This diagram shows the flow from the client interface through the query, transaction, and caching layers down to the file I/O and filesystem abstraction layers.

Sources: IMPLEMENTATION_PLAN.md:24-42, README.md:131-141

Data Storage Model

Sentinel uses a straightforward folder and file structure to represent its data. Collections are directories, and documents are files within those directories.

A standard document includes user data as well as reserved metadata fields for versioning, timestamps, and integrity checks.

{
  "_id": "user-123",
  "_ts": "2026-01-11T12:00:00Z",
  "_v": 3,
  "_hash": "sha256:abc123...",
  "_sig": "rsa2048:def456...",
  "name": "Alice",
  "email": "alice@example.com",
  "role": "admin",
  "encrypted_fields": ["password_hash"]
}

Sources: IMPLEMENTATION_PLAN.md:68-80

Core Components

The implementation plan details several key Rust structs that form the core of the system.

Sources: IMPLEMENTATION_PLAN.md:84-297

Store and Collection

The Store manages the root of the database and its collections, while the Collection handles operations on documents within it.

Document and Metadata

Each record is represented by a Document struct, which contains the data (serde_json::Value) and associated DocumentMetadata.

Features & Roadmap

The project is planned in multiple phases, starting with core DBMS functionality and progressing to enterprise-grade and advanced features.

Phase	Key Features
1	Document storage as files, Collections, CRUD, JSON format, Basic filtering, Transactions, File encryption.
2	Write-Ahead Logging (WAL), File locking, In-memory caching, Indexing, Full-text search, Git replication.
3	MVCC, Backup/restore utilities, Compliance reporting, Audit trail generation, Encryption at rest, ACLs.
4	Distributed consensus (Raft), Content-addressable storage, Merkle tree verification, Temporal queries.

Sources: README.md:98-119, IMPLEMENTATION_PLAN.md:321-411

Basic Usage

Interacting with Sentinel is done through a Rust API. The following example demonstrates creating a store, managing a collection, and performing CRUD operations.

use cyberpath_sentinel::Store;

// Create a store (creates data/ folder)
let store = Store::new("./data").expect("Failed to create store");

// Create a collection (creates data/users/ folder)
let users = store.collection("users").expect("Failed to create collection");

// Insert a document (creates data/users/user-123.json)
users.insert("user-123", json!({
    "name": "Alice",
    "email": "alice@example.com"
})).expect("Failed to insert");

// Query documents
let user = users.get("user-123").expect("Failed to get");

// Delete a document (moves to data/users/.deleted/user-123.json)
users.delete("user-123").expect("Failed to delete");

Sources: README.md:52-81

The following sequence diagram illustrates the insert operation.

Performance

Performance characteristics are determined by the underlying filesystem operations.

Operation	Time Complexity	Notes
Insert	O(1)	Single file write
Get	O(1)	Direct filename lookup
Delete	O(1)	Rename to .deleted/
Update	O(1)	Atomic file rename
List	O(n)	Scan directory for filenames
Filter	O(n)	Scan all files in collection
Index	O(n)	Build lazy indices on first query

Sources: README.md:158-168

Project Configuration

The project is structured as a Cargo workspace. The root Cargo.toml defines workspace members, package metadata, release profile optimizations, and extensive linting rules via clippy.

Sources: Cargo.toml:1-10, 12-23, 25-455

The release profile is heavily optimized for performance and small binary size, enabling Link Time Optimization (LTO), and disabling debug info and overflow checks.

Sources: Cargo.toml:12-23

Code formatting is standardized across the project using rustfmt with a detailed configuration specified in rustfmt.toml.

Sources: rustfmt.toml

Contributing

Contributions are welcome. The project has a CODE_OF_CONDUCT.md that outlines standards for community interaction, based on the Contributor Covenant. All participants are expected to adhere to these guidelines to foster an open and inclusive environment.

Sources: README.md:190-197, CODE_OF_CONDUCT.md

Vision

The long-term vision for Cyberpath Sentinel is to become the gold standard for transparent and auditable data storage. It is not intended to compete on speed with transactional databases but to provide a new tool for organizations where accountability, security, and transparency are the primary drivers. The goal is to be synonymous with "Compliance as Code" and "Security by Design".

Sources: README.md:203-215