Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Cyberpath Sentinel is a document-based Database Management System (DBMS) written in Rust. Its architecture is fundamentally designed around the principle of using the filesystem as the database. This approach prioritizes trust, transparency, auditability, and compliance over raw performance, making it suitable for use cases like audit logs, certificate management, and regulatory reporting. All data is stored as files on disk, where tables are represented by folders and each document's primary key corresponds to a filename.
The system is designed with zero external dependencies for its core functionality, enabling it to run on edge devices and in disconnected environments. The architecture is layered, starting from a client-facing API, moving down through query and transaction management, and finally interacting with the filesystem. For more details on the planned implementation, see the Implementation Plan.
Sources: README.md:1-12, IMPLEMENTATION_PLAN.md:13-22
Design Principles
The architecture of Sentinel is guided by a set of core principles that influence every design decision.
- Filesystem is the Database: The system leverages the reliability, maturity, and tooling of modern operating system filesystems (e.g., ext4, NTFS, APFS).
- Immutability by Default: Changes are handled through append-only patterns and soft deletes, preserving a complete audit trail.
- Security First: Security is built-in through file permissions, optional encryption, and cryptographic verification.
- UNIX Philosophy: The system is designed to do one thing well (auditable storage) and compose with standard tools like
rsync,tar, andgrep. - Zero External Dependencies: The core database can operate offline and on any device with a filesystem, without requiring a server.
Sources: README.md:126-132
System Design
The overall system is composed of several layers, each with distinct responsibilities. The client interacts with the top layer, and requests flow down to the filesystem.
This diagram illustrates the high-level system architecture, showing the flow from the client down to the filesystem abstraction layer.
Data Storage Model
Sentinel's data model directly maps database concepts to filesystem structures.
- A Store is the root directory for the database.
- A Collection is a subdirectory within the store.
- A Document is a file (typically JSON) within a collection's directory, with its filename serving as the primary key.
Folder Structure
The following diagram shows the planned folder structure for a Sentinel store.
Sources: README.md:88-99, IMPLEMENTATION_PLAN.md:46-66
Document Format
Documents are stored in JSON format and are planned to include 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-81
Core Components
The implementation plan details several core components that form the engine of Sentinel.
1. Store Manager
The Store is the top-level object that manages the database root, its configuration, and access to collections.
Sources: IMPLEMENTATION_PLAN.md:85-110
2. Collection Manager
The Collection manages all operations for a set of documents within a specific folder, handling CRUD, queries, and transactions.
Sources: IMPLEMENTATION_PLAN.md:118-161
3. Write-Ahead Logging (WAL)
To ensure durability and crash recovery, a Write-Ahead Log is planned. All state-changing operations are first written to a log file before being applied to the main data files.
This sequence diagram shows how an insert operation would use the WAL.
Sources: IMPLEMENTATION_PLAN.md:163-182
4. Concurrency Control & Locking
To handle multi-writer scenarios, a FileLockManager is proposed. It will use strategies like exclusive and shared locks, with plans for more advanced Multi-Version Concurrency Control (MVCC).
Sources: IMPLEMENTATION_PLAN.md:184-205
5. Caching Layer
An in-memory LRU (Least Recently Used) cache is planned to improve performance for frequently accessed documents, reducing disk I/O.
Sources: IMPLEMENTATION_PLAN.md:207-224
6. Indexing Engine
To avoid slow full-collection scans, a lazy-built indexing engine is part of the design. Indices will be created on the first query against a field and stored in the .index/ directory.
| Index Type | Time Complexity | Use Case |
|---|---|---|
| Hash | O(1) | Exact matches |
| B-Tree | O(log n) | Range queries |
| FullText | N/A | Text search |
Sources: IMPLEMENTATION_PLAN.md:226-250
7. Replication Manager
Replication is designed around Git, leveraging its efficient data transfer and versioning capabilities. This allows for push/pull synchronization and a complete, auditable history of the database state.
Sources: IMPLEMENTATION_PLAN.md:315-338
Performance Characteristics
The architecture's performance is directly tied to filesystem operations. The following table summarizes the expected time complexity for various operations.
| Operation | Time Complexity | Notes |
|---|---|---|
| Insert | O(1) | Single file write |
| Get | O(1) | Direct filename lookup |
| Delete | O(1) | Rename to .deleted/ folder |
| Update | O(1) | Atomic file rename |
| List | O(n) | Scan directory for filenames |
| Filter | O(n) | Scan all files in collection (without index) |
| Index | O(n) | Build lazy indices on first query |
Sources: README.md:183-193
Technology Stack
The project is built in Rust and relies on a curated set of dependencies for asynchronous operations, serialization, and concurrency. The release profile is configured for maximum optimization and security.
- Async Runtime:
tokio - Serialization:
serde,serde_json,bincode - Concurrency:
parking_lot,dashmap - Encryption:
aes-gcm,chacha20poly1305,rsa - Git Operations:
git2
The Cargo.toml specifies a release profile that enables Link Time Optimization (LTO), aborts on panic, and strips symbols to produce a small, secure, and optimized binary.
Sources: IMPLEMENTATION_PLAN.md:586-628, Cargo.toml:11-20
Conclusion
The architecture of Cyberpath Sentinel is a deliberate trade-off, prioritizing auditability, simplicity, and security over the high-throughput performance of traditional databases. By building directly on the filesystem and leveraging standard tools and formats, it provides a "transparency layer" for data that must be inspectable and compliant by design. The layered component model, from the Store and Collection managers down to the WAL and encryption layers, creates a robust foundation for building a trustworthy data storage system.
Sources: README.md:3-6, IMPLEMENTATION_PLAN.md:13-17