Quick Start Guide
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. It prioritizes trust, transparency, and compliance by storing all data as files on disk. This design makes every piece of data inspectable, auditable, and compliant by design. Instead of focusing on the high-speed transactions of modern databases, Sentinel is built for use cases where auditability is paramount, such as audit logs, certificate management, and compliance rule storage.
The core principle is "Filesystem is the Database," leveraging the reliability and tooling of the operating system. Tables are represented by folders, and each document's primary key is its filename. This approach allows for operational simplicity, using standard UNIX tools like grep, rsync, and git for querying, replication, and versioning. For more details, see the Implementation Plan.
Sources: README.md:9-13, 40-44, IMPLEMENTATION_PLAN.md:14-22
Installation
You can install Sentinel using cargo or by cloning the repository directly.
Using Cargo
cargo install cyberpath-sentinel
Sources: README.md:83-84
From Source
git clone https://github.com/cyberpath-HQ/cyberpath-sentinel
cd cyberpath-sentinel
cargo build --release
Sources: README.md:85-88
Basic Usage
The following example demonstrates the fundamental CRUD (Create, Read, Update, Delete) operations using the Sentinel Rust library.
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",
"role": "admin",
"created_at": "2026-01-11T12:00:00Z"
})).expect("Failed to insert");
// Query documents
let user = users.get("user-123").expect("Failed to get");
println!("{}", user);
// List all documents
let all_users = users.list().expect("Failed to list");
for user_id in all_users {
println!("{}", user_id);
}
// Update a document
users.update("user-123", json!({
"name": "Alice",
"email": "alice.smith@example.com",
"role": "admin",
"created_at": "2026-01-11T12:00:00Z"
})).expect("Failed to update");
// Delete a document (moves to data/users/.deleted/user-123.json)
users.delete("user-123").expect("Failed to delete");
// Query with filters
let admins = users.filter(|doc| {
doc["role"].as_str().unwrap_or("") == "admin"
}).expect("Failed to filter");
Sources: README.md:91-131
This sequence of operations results in a specific folder structure on the filesystem.
Folder Structure
The database operations map directly to filesystem operations, creating a human-readable structure.
data/
├── users/
│ ├── user-123.json
│ ├── user-456.json
│ └── .deleted/
│ └── user-789.json
├── audit_logs/
│ ├── audit-2026-01-01.json
│ └── audit-2026-01-02.json
└── certs/
├── cert-a1b2c3.pem
└── cert-d4e5f6.pem
Sources: README.md:134-147
A more detailed view of the data storage model includes metadata and index files within each collection folder.
data/
├── users/
│ ├── .metadata.json # Collection metadata (indices, settings)
│ ├── .deleted/ # Soft-deleted documents
│ ├── .index/ # Lazy-built indices
│ ├── user-123.json # Primary document
...
Sources: IMPLEMENTATION_PLAN.md:43-54
Core Concepts
Architecture
Sentinel's architecture is layered to separate concerns, from the high-level client API down to the filesystem interactions.
The diagram below shows the main components of the Sentinel system.
This diagram illustrates the flow from client requests through the core logic and down to the filesystem.
Sources: README.md:183-195, IMPLEMENTATION_PLAN.md:27-40
Data Flow for an Insert Operation
When a document is inserted, it passes through several components to ensure durability, consistency, and security.
This sequence ensures that operations are logged for durability before being written to disk, with locks preventing race conditions.
Sources: IMPLEMENTATION_PLAN.md:118-132, 148-163
Data Model
Each document stored in Sentinel is a JSON file. In addition to user-defined data, Sentinel adds metadata fields for versioning, timestamps, and integrity checks.
| Field | Description |
|---|---|
_id | The document's primary key, which is also the filename. |
_ts | Timestamp of the last update. |
_v | The version number of the document. |
_hash | A cryptographic hash (e.g., SHA-256) of the document content for integrity. |
_sig | A digital signature (e.g., RSA-2048) to verify the author. |
Sources: IMPLEMENTATION_PLAN.md:57-67
Performance
Sentinel is not designed for high-frequency trading but offers predictable performance for its target use cases. The time complexity of operations is directly related to filesystem performance.
| Operation | Time Complexity | Notes |
|---|---|---|
| Insert | O(1) | A single file write operation. |
| Get | O(1) | Direct lookup by filename. |
| Delete | O(1) | A file rename operation (move to .deleted/). |
| Update | O(1) | An atomic file rename operation. |
| List | O(n) | Scans the directory to list all filenames. |
| Filter | O(n) | Scans all files within the collection. |
Sources: README.md:216-225
Deployment
Sentinel can be deployed in various configurations depending on the need for availability and replication.
Single Machine
A simple server can be run to provide access to a local store.
# Initialize store
cyberpath-sentinel init --path /var/cyberpath
# Run server
cyberpath-sentinel serve --path /var/cyberpath --port 8080
Sources: README.md:233-239
Replicated Cluster (Git-backed)
For disaster recovery and replication, Sentinel can integrate with Git to synchronize data between nodes.
# Primary node
git init --bare /data/cyberpath.git
cyberpath-sentinel serve --path /data/cyberpath --git-push origin main
# Secondary node
git clone /data/cyberpath.git /data/cyberpath
cyberpath-sentinel serve --path /data/cyberpath --git-pull origin main
Sources: README.md:241-249
Project Structure and Dependencies
The project is organized as a Cargo workspace. The core logic resides in the sentinel crate.
.
├── Cargo.toml # Workspace configuration
├── crates/
│ └── sentinel/
│ ├── Cargo.toml # Crate-specific dependencies
│ └── src/
│ └── lib.rs # Crate root
...
The main workspace Cargo.toml defines shared properties and strict linting rules to ensure code quality.
Sources: Cargo.toml:1-5, 18-349, crates/sentinel/Cargo.toml:1-7