Architecture¶

Understand how Grafeo is designed and implemented.

Overview¶

Grafeo is built as a modular system with clear separation of concerns:

graph TB
    subgraph "User Interface"
        PY[Python API]
        RS[Rust API]
        JS[Node.js API]
        WA[WASM API]
        CC[C/Go/C#/Dart FFI]
    end

    subgraph "grafeo-engine"
        DB[Database]
        SESS[Session Manager]
        QP[Query Processor]
        TXN[Transaction Manager]
    end

    subgraph "grafeo-adapters"
        GQL[GQL Parser]
        WAL[WAL Storage]
        PLUG[Plugins]
    end

    subgraph "grafeo-core"
        LPG[LPG Store]
        IDX[Indexes]
        EXEC[Execution Engine]
    end

    subgraph "grafeo-common"
        TYPES[Types]
        MEM[Memory]
        UTIL[Utilities]
    end

    PY --> DB
    RS --> DB
    JS --> DB
    WA --> DB
    CC --> DB
    DB --> SESS
    SESS --> QP
    SESS --> TXN
    QP --> GQL
    QP --> EXEC
    TXN --> LPG
    EXEC --> LPG
    EXEC --> IDX
    LPG --> TYPES
    IDX --> MEM

Sections¶

System Overview

High-level architecture, design principles and query flow.
Crate Structure

The crates and their responsibilities.
Storage Model

Columnar properties, chunked adjacency lists, compression.
Execution Engine

Push-based vectorized execution and parallelism.
Query Optimization

Cost-based optimization, join ordering, cardinality estimation.
Memory Management

Buffer manager, arena allocators, spill-to-disk.
Transactions

MVCC, snapshot isolation, conflict detection.

Design Principles¶

Performance First - Batch-at-a-time vectorized execution, columnar storage, morsel-driven parallelism
Embeddable - No required C dependencies, single library
Safe - Written in safe Rust, memory-safe by design
Modular - Clear crate boundaries, strict layering
Extensible - Plugin architecture, multiple storage backends