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
│   └── string_store.rs   # append-only deduplicated string store
└── docs/                 # repo-local notes (design lives in the wiki)

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	Design
Index	In-memory and/or on-disk lookup structures	Design
Graph API	Node/edge/property create, read, traverse	Planned

---

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	Run criterion benchmarks (intern, resolve, save/open, compression ratio)
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: fixed-length node / property records (Small Profile)
v0.2	Value type encoding for the 16-byte property buffer
v0.3	Index module; long-value routing into the String Store
v0.3	String Store: optional Bloom filter; incremental on-disk append
v0.4	Graph API (create / read / traverse)
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