Architecture

System overview

flowchart LR
    subgraph Client layer
        PY[Python SDK\nhypermeshdb.Connection]
        TS[TypeScript SDK\n@hypermeshdb/client]
        CLI[hmdb CLI]
    end

    subgraph Server layer
        API[FastAPI REST API\nhmdb serve]
    end

    subgraph Engine layer
        CONN[Connection]
        PARSER[Cypher Parser\nparser.c]
        STRATEGY{Strategy\nrouter}
    end

    subgraph Storage layer
        TPI[TPI Binary Index\nevent_ts buckets]
        FMI[FMI Membership Index\nnode → edge list]
        PSI[PSI Property Index\nnumeric properties]
        WAL[WAL\nWrite-Ahead Log]
        SCHEMA[(Schema DB\nSQLite)]
    end

    PY --> CONN
    CLI --> CONN
    TS -->|HTTP| API
    API --> CONN

    CONN --> PARSER
    PARSER --> STRATEGY
    STRATEGY -->|TPI pushdown| TPI
    STRATEGY -->|FMI lookup| FMI
    STRATEGY -->|PSI scan| PSI
    STRATEGY -->|write| WAL
    WAL -->|compact| TPI & FMI

    CONN --> SCHEMA

Component descriptions

Cypher Parser (parser.c)

A hand-written recursive-descent parser for the HyperMesh Cypher dialect. Produces an HmQueryAst struct consumed by the C query executor.

Supports: MATCH HYPEREDGE, INSERT, DELETE, UPDATE, CREATE/DROP TABLE, CREATE/DROP INDEX, SHOW INDEXES, COPY FROM, CALL SHOW_HYPEREDGE_TABLES(), multi-pattern MATCH (cross-table joins), COMPACT_THRESHOLD DDL.

TPI (Temporal Property Index)

A compact binary file partitioned into fixed-size time buckets.

• O(1) bucket seek: bucket = event_ts / bucket_seconds
• O(k) read: read only the matching bucket segments
• Supports TTL compaction: buckets older than now - ttl are skipped entirely

FMI (Forward Member Index)

A sorted binary index mapping node_id → list of (event_ts, edge_offset).

• O(log N) node lookup via binary search
• Updated atomically during WAL compaction

PSI (Property Secondary Index)

Numeric property indexes built over arbitrary REAL or INTEGER columns.

• Supports =, >, >=, <, <= predicates
• Created with CREATE INDEX ON table (column)

WAL (Write-Ahead Log)

Records are first appended to the WAL. On compaction:

1. WAL entries are sorted by event_ts
2. Merged into the TPI and FMI indexes
3. Tombstones cancel matching inserts
4. TTL-expired records are discarded

HypergraphPy Analytics Bridge

An in-process Python analytics layer using SciPy sparse matrices.

• Builds a bipartite incidence matrix B (nodes × hyperedges) from the TPI
• Computes 25 measures including spectral, centrality, clustering, and temporal
• Zero network overhead — runs in the same process as the Python SDK

File layout

/data/                          ← HMDB_DIR
  schema.db                     ← SQLite schema catalog
  CoProximity/                  ← one directory per table
    hyperedges.bin              ← TPI binary index
    wal.bin                     ← WAL (compacted away on COMPACT)
    fmi.bin                     ← FMI membership index
    weight.psi                  ← PSI for "weight" column (if created)
  Events/
    ...