# Architecture overview

MoonPropertyDB is an embedded MoonBit property-graph library. The current
snapshot includes an in-memory graph, file-backed transaction log and replay.
Snapshots, the query layer and CLI remain planned v0.1 work.

## Current package boundary

The repository currently uses one root MoonBit package while the implementation
is split into cohesive source files:

```text
model.mbt          scalar values, node/edge IDs, detached records
errors.mbt         structured public error categories
graph.mbt          private graph state, adjacency and secondary indexes
database.mbt       public in-memory and file-backed database boundary
transaction.mbt    detached candidate, async commit and rollback lifecycle
codec.mbt          private versioned WAL framing and checksum
wal_operations.mbt deterministic graph-operation encoding and replay
wal_storage.mbt    append and synchronize one complete WAL record
persistent_storage.mbt init, open, lock, recovery and tail repair
*_test.mbt         public and white-box behavior tests
examples/          runnable in-memory example
```

The public generated interface is reviewed through `pkg.generated.mbti`.
Private graph and index representations do not cross the `Database` boundary.

## Implemented foundation

The current code supports typed IDs, scalar properties, graph CRUD,
endpoint validation, adjacency and secondary indexes, structured failures,
and a single active writer over a detached candidate graph. Persistent
`Database::init(path)` and `Database::open(path)` hold an advisory exclusive
lock. Async commit appends and synchronizes one tagged WAL record before
publishing the candidate. Open validates and sequentially replays complete
records, rebuilds derived indexes, and repairs an incomplete final tail before
allowing later commits. A failed write poisons its transaction; ambiguous WAL
I/O requires close and reopen.

`Database::new_in_memory()` remains available for transient use. Persistent
open currently reads the full WAL into memory; compaction and snapshots are
not implemented.

## Planned v0.1 layers

```text
Application / CLI
        |
        v
Public Database API
        |
  +-----+------------------+
  |                        |
  v                        v
Transaction manager    Lexer -> Parser/AST -> Validator
  |                                      -> Planner -> Executor
  v                        |
Candidate graph state <----+
  |
  +-- ID maps, adjacency, label/type indexes, equality indexes
  |
  v
Versioned commit log + snapshots/checkpoints
```

The planned storage work adds snapshots and checkpoint publication. The
planned query layer is a bounded read-only graph subset, not full openCypher.
The query layer, CLI and complete dependency-graph example are still to be
implemented.

## Correctness boundaries

The design excludes multi-writer concurrency, MVCC, distributed transactions,
range/composite/full-text/vector indexes, network serving, and browser/Wasm
persistence. Durability and recovery claims are limited to the tested native
append, synchronization and replay path. Snapshot, query and CLI claims require
their own implementations and integration tests.