Architecture

Architecture

mGraphDB is a single Rust crate (mgraphdb) made of small, layered modules. The design favours a minimal, embeddable footprint (SQLite-like) and exposes several abstraction layers so callers can work at the level they need.

Crate layout

mgraphdb (Rust crate)
├── Cargo.toml
├── src/
│   ├── lib.rs            # crate root, re-exports modules
│   ├── main.rs           # small demo binary
│   ├── string_store.rs   # append-only deduplicated string store
│   ├── node_store.rs     # fixed-length 12-byte node records
│   ├── prop_store.rs     # fixed-length 16-byte property/edge records
│   ├── index_store.rs    # CSR adjacency index (node → owned records)
│   └── graph.rs          # Graph API: facade over all four layers
└── docs/                 # repo-local notes (design lives in this wiki)

Modules

Module	Responsibility	Status
String Store	Deduplicated UTF-8 storage for long/shared values	Implemented (v1)
Persistent Layer	Fixed-length node / edge / property records (Small Profile)	Implemented (v1)
Index	CSR adjacency: node → owned edge/property records	Implemented (v1)
Graph API	Node / edge / property create, read, traverse	Implemented (v1)

How the layers fit together

        Graph API            create / read / traverse  (implemented)
            │
        Persistent Layer     fixed-length node/edge/property records
            │   │
            │   └── Index     resolve IDs and adjacency
            │
        String Store         long values referenced by StrId / StrHash

• The Graph API is the public surface: nodes, edges, properties, traversal.
• The Persistent Layer holds the fixed-length records that make every element directly addressable by a compact integer ID. Edges and properties share a 16-byte record.
• The Index is a CSR (compressed-sparse-row) adjacency map: each node points at a contiguous slice of the edge/property records it owns. It is a derived view — rebuildable from the stores, kept in memory, or dropped to save disk.
• The String Store holds values too large for the 16-byte property buffer (long strings, URLs, text), addressed from records by StrId.

Cross-cutting principles

• Everything is a node. Edges and properties are node specialisations — one addressing scheme, one record discipline. See General Concepts.
• Configuration over forks. A single persistent layer covers different needs through profiles (Small first; speed-oriented later) rather than parallel implementations.
• Little-endian, append-only on disk. Stable, portable segment files.
• No unsafe in the project's own crates; zero compiler/Clippy warnings.

See the Software Development Plan for process, build, and roadmap, and the Requirements page for the numbered, traceable design.