SDP

Software Development Plan — mGraphDB

Version: 0.1 Status: Active

---

1. Project overview

mGraphDB is an embedded graph database published under the MIT License. It is designed to be small enough to embed (in the spirit of SQLite) while exposing several abstraction layers.

• Rust is the primary implementation (performance, memory safety).
• Swift is planned for direct integration into iOS / macOS software.
• The database is schema-less: no type definitions are required; ontologies and schemas live as nodes in the graph and act as a descriptive viewpoint, not as storage-engine constraints. See General Concepts.
• Full ACID support is explicitly out of scope for now.

The data model is uniform: everything is a node — edges and properties are specialisations of a node. See General Concepts.

---

2. System architecture

mgraphdb (Rust crate)
├── Cargo.toml
├── src/
│   ├── lib.rs            # crate root, re-exports modules
│   ├── main.rs           # small demo binary (Graph API in action)
│   ├── 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
│   └── graph.rs          # Graph API facade
└── benches/              # criterion benchmarks (string_store, graph)

Planned modules (see Architecture):

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

---

3. Development workflow

3.1 Branching

main                 ← stable
  └── feat/<name>    ← feature branches, merged via PR
  └── fix/<name>

Never commit directly to main; merge via pull request.

3.2 Commit conventions

This repo uses Conventional Commits, enforced by a commit-msg Git hook under .githooks/ (template in .gitmessage.txt).

<type>(<scope>)!: <subject>
Types: feat | fix | docs | style | refactor | perf | test | build | ci | chore | revert

! (or a BREAKING CHANGE: footer) marks a breaking change.

3.3 Development cycle

1. git checkout -b feat/<name>
2. <edit code>
3. cargo test                          # all unit tests must pass
4. cargo clippy --all-targets -- -D warnings   # zero warnings
5. git commit            # commit-msg hook validates the message
6. git push && open PR

---

4. Build system

Command	Description
cargo build	Debug build
cargo build --release	Optimised build
cargo run	Run the demo binary
cargo test	Run unit + doc tests
cargo clippy --all-targets -- -D warnings	Lint gate (zero warnings)
cargo bench --bench string_store	String Store benchmarks (intern, resolve, save/open, compression ratio)
cargo bench --bench graph	Graph benchmarks (build, traverse, build_index, save/open)
cargo bench -- compression_ratio	Print compression ratio table for LZ4 / Zstd

Prerequisites: Rust 1.94+ / Cargo (edition 2024).

---

5. Requirements

Numbered functional and non-functional requirements live on the Requirements page. Each requirement is traced to a verification method on the Test Plan page.

---

6. Testing

• Unit tests live next to the code (#[cfg(test)]). The String Store ships with 7 unit tests covering dedup, resolve-by-id/hash, missing lookups, empty/Unicode strings, save/open roundtrip, multi-block roundtrip, and corruption rejection.
• Quality gate: cargo clippy --all-targets -- -D warnings must be clean.

See the Test Plan for the requirement-to-test matrix.

---

7. Code quality KPIs

KPI	Tool	Target
Unit test pass rate	cargo test	100%
Clippy lints	cargo clippy -- -D warnings	0 warnings
Compiler warnings	cargo build	0 warnings
Unsafe code	review	none in our own crates
Test coverage	cargo llvm-cov	≥ 80% (backlog)

---

8. Roadmap

Milestone	Items
v0.1	String Store v1 (in-RAM + single on-disk segment) ✓
v0.2	String Store v2: LZ4 + Zstd block compression (Compression enum) ✓
v0.2	String Store criterion benchmarks (English words + ontology URIs) ✓
v0.2	Persistent Layer: Node Store, Option 2, u32 IDs, 12-byte records ✓
v0.2	Persistent Layer: Property / Edge Store (16-byte records) ✓
v0.2	Value type encoding for the 16-byte property buffer ✓
v0.3	Index module (CSR adjacency: IndexStore + IndexBuilder) ✓
v0.3	Long-value routing into the String Store (REQ-22), via Graph::set_str ✓
v0.3	String Store: optional Bloom filter; incremental on-disk append
v0.4	Graph API (create / read / traverse), demo binary, graph benchmarks ✓
v0.4	Graph API: incoming-edge traversal; node deletion ✓
v0.4	Property keys + edge labels (in-record NodeId; get_property / edges_of_type) ✓
v0.4	Find by value (find_by_property / find_by_str / find_by_key; scan-based) ✓
v0.4	Edge-list import (from_edge_list) + real-world ca-HepTh benchmark ✓
v0.5	Secondary inverted index (key, value) → [node] to replace find scans
v0.4	String Store: lazy decompression — keep blocks compressed on disk, decompress entries on demand (REQ-24)
v0.5	String Store: FSST compression as third algorithm, contingent on REQ-24 and a production-ready Arrow-free Rust crate (REQ-25)
later	Swift implementation; performance profiles

---

9. Revision history

Version	Date	Changes
0.1	2026-06-07	Initial SDP; String Store v1 documented; requirements and test plan added
0.2	2026-06-09	PropStore implemented; v0.2 persistent layer milestones complete
0.3	2026-06-14	CSR adjacency Index (IndexStore/IndexBuilder) implemented; REQ-38 added
0.4	2026-06-23	Graph API (facade, long-string routing, persistence), demo binary, graph benchmarks; REQ-01–03/22/60–63
0.4	2026-06-28	Incoming-edge traversal (REQ-64); node deletion (REQ-65); property keys + edge labels (REQ-66, INLINE_STR_MAX 14→10); find by value (REQ-67); edge-list import + ca-HepTh benchmark (REQ-68)