Directory Structure

Relevant source files

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

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

Introduction

Cyberpath Sentinel's core design principle is "Filesystem is the Database". This means all data is stored as files and folders on disk, making the entire database inspectable, auditable, and manageable with standard command-line tools. The directory structure is not just a physical layout but a logical representation of the database itself, where tables are folders and documents are files.

This structure is fundamental to achieving Sentinel's goals of trust, transparency, and compliance. By leveraging the native filesystem, Sentinel inherits OS-level reliability and security features, such as Access Control Lists (ACLs), while enabling simple operational workflows for backup (tar), replication (rsync), and versioning (git).

Sources: README.md:10-12, README.md:121-122

Project Source Code Structure

The Sentinel project is organized as a Rust workspace. The top-level Cargo.toml file defines the workspace members, which are located in the crates/ directory.

Sources: Cargo.toml:2-5

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

Sources: Cargo.toml:1-5

This diagram illustrates the high-level layout of the source code repository.

Key Directories & Files

Path	Description
crates/	Contains all Rust crates that are part of the workspace.
crates/sentinel/	The main crate for the Sentinel database logic.
crates/sentinel/src/lib.rs	The library entry point for the sentinel crate.
.assets/	Contains static assets like logos used in documentation.
README.md	The main project overview, including quick start and feature lists.
IMPLEMENTATION_PLAN.md	A detailed document outlining the architecture and feature specifications.
Cargo.toml	The workspace manifest defining project members and dependencies.

Sources: Cargo.toml:2-5, README.md:4-8, IMPLEMENTATION_PLAN.md, crates/sentinel/src/lib.rs

Data Storage Structure

Sentinel's data storage model directly maps database concepts to filesystem structures. A Store is the root data directory, a Collection is a sub-directory, and a Document is a file within a collection directory.

Sources: README.md:10-12, README.md:92-97

Basic Structure

The following is a basic example of the data directory layout. The root is data/, which contains collections like users, audit_logs, and certs. Each document is a file within its respective collection folder.

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:91-104

Detailed Collection Structure

The implementation plan specifies a more detailed structure within each collection folder to support advanced features like transactions, indexing, and compliance.

This diagram shows the planned internal structure of a single collection folder.

The detailed structure is planned as follows:

data/
├── users/
│   ├── .metadata.json          # Collection metadata (indices, settings)
│   ├── .deleted/               # Soft-deleted documents
│   │   └── user-123.json
│   ├── .index/                 # Lazy-built indices
│   │   ├── email.idx           # Hash index for email field
│   │   └── role.idx            # Value index for role field
│   ├── user-123.json           # Primary document
│   ├── user-456.json
│   └── user-789.json
├── audit_logs/
│   ├── .wal/                   # Write-Ahead Log for durability
│   ├── audit-2026-01-01.json
│   └── audit-2026-01-02.json

Sources: IMPLEMENTATION_PLAN.md:49-65

Special Directories and Files

The functionality of Sentinel is extended through special-purpose directories and files, typically prefixed with a dot (.) to indicate they are hidden or contain metadata.

Name	Type	Location	Purpose
.deleted/	Directory	Collection	Stores soft-deleted documents, enabling recovery and maintaining an audit trail.
.index/	Directory	Collection	Contains lazy-built index files (e.g., hash or B-Tree) to accelerate queries.
.wal/	Directory	Collection	Holds the Write-Ahead Log for transaction durability and crash recovery.
.metadata.json	File	Collection	Stores collection-specific configuration, such as index definitions and settings.
.audit/	Directory	Collection	Proposed for storing per-document audit events like creation, updates, and deletion.

Sources: README.md:86, IMPLEMENTATION_PLAN.md:49-65, IMPLEMENTATION_PLAN.md:330-343

Compliance and Auditing Structure

For enhanced compliance tracking, a specific directory structure is proposed to separate user data from audit logs and compliance artifacts. This ensures that audit trails are immutable and easily accessible for reporting.

data/
├── users/
│   ├── user-123.json
│   └── .audit/
│       ├── created.json
│       ├── updated.json
│       └── deleted.json
├── audit_logs/
│   ├── 2026-01-01.log
│   └── 2026-01-02.log
└── compliance/
    ├── gdpr_consents.json
    ├── data_inventory.json
    └── retention_policies.json

Sources: IMPLEMENTATION_PLAN.md:330-343

This structure segregates data into three main categories:

1. Primary Data (users/): Contains the operational data. An .audit/ sub-directory within each document's collection could track its lifecycle.
2. Immutable Logs (audit_logs/): A dedicated, append-only collection for storing all system-wide audit events.
3. Compliance Artifacts (compliance/): Stores data and policies related to specific regulations like GDPR.

Sources: IMPLEMENTATION_PLAN.md:330-343