# freshair129/genesisblock architecture

> Architecture diagram of the GitHub repository freshair129/genesisblock, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/freshair129/genesisblock
- Repository: https://github.com/freshair129/genesisblock

## Overview

GenesisBlockDB is an embedded, local-first hybrid graph and vector database, also exposed as a REST server and through language, agent, and mobile bindings. The main workflow is a client submitting knowledge or a query, an interface dispatching it to the Rust engine, and the engine persisting or retrieving graph, vector, and temporal context. The README documents WAL durability, provenance primitives, and optional CRDT synchronization. Core internals are represented at the supported module level; detailed wiring for unsampled subsystems is not inferred.

Main entry points: [`src/lib.rs`](https://github.com/freshair129/genesisblock/blob/main/src/lib.rs) (Storage engine), [`src/main.rs`](https://github.com/freshair129/genesisblock/blob/main/src/main.rs) (REST server), [`src/router.rs`](https://github.com/freshair129/genesisblock/blob/main/src/router.rs) (REST router), [`src/query/mod.rs`](https://github.com/freshair129/genesisblock/blob/main/src/query/mod.rs) (HQL and Query IR)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Access interfaces"]
  node_node_binding["Node binding<br/>[index.js]"]
  node_rest_server["REST server<br/>[main.rs]"]
  node_rest_router["REST router<br/>[router.rs]"]
  node_mcp["MCP server<br/>[server.js]"]
  node_go_sdk["Go SDK<br/>[client.go]"]
  node_python_sdk["Python SDK<br/>[client.py]"]
  node_mobile_sdk["Mobile bindings<br/>[index.ts]"]
end

subgraph group_query["Query and retrieval"]
  node_query_api["HQL and Query IR<br/>[mod.rs]"]
  node_query_ast["Query AST<br/>[ast.rs]"]
  node_context["Tiered context<br/>[lib.rs]"]
end

subgraph group_engine["Database engine"]
  node_storage[("Storage engine<br/>[lib.rs]")]
  node_graph["Property graph<br/>[lib.rs]"]
  node_vectors["Vector search<br/>[lib.rs]"]
  node_temporal["Temporal history<br/>[lib.rs]"]
  node_provenance["Provenance primitives<br/>[lib.rs]"]
end

subgraph group_state["Durable state"]
  node_wal[("WAL and recovery<br/>[lib.rs]")]
  node_projection[("SQLite projection<br/>[lib.rs]")]
  node_crdt["CRDT synchronization<br/>[lib.rs]"]
end

subgraph group_clients["Client applications"]
  node_obsidian["Obsidian plugin<br/>[main.ts]"]
  node_mobile_app["Mobile app<br/>[App.tsx]"]
  node_studio["Studio graph explorer<br/>[App.tsx]"]
end

node_app_user(("Application or agent"))

node_app_user -->|"opens embedded"| node_node_binding
node_app_user -->|"sends requests"| node_rest_server
node_app_user -->|"invokes tools"| node_mcp
node_app_user -->|"uses SDK"| node_go_sdk
node_app_user -->|"uses SDK"| node_python_sdk
node_node_binding -->|"calls engine"| node_storage
node_rest_server -->|"opens store"| node_storage
node_rest_server -->|"builds router"| node_rest_router
node_rest_router -->|"dispatches operations"| node_storage
node_rest_router -->|"dispatches queries"| node_query_api
node_mcp -->|"opens database"| node_node_binding
node_go_sdk -->|"HTTP requests"| node_rest_server
node_python_sdk -->|"HTTP requests"| node_rest_server
node_mobile_sdk -->|"connects to API"| node_rest_server
node_query_api -->|"parses queries"| node_query_ast
node_query_api -->|"executes queries"| node_storage
node_storage -->|"manages graph"| node_graph
node_storage -->|"indexes vectors"| node_vectors
node_storage -->|"records history"| node_temporal
node_storage -->|"supports provenance"| node_provenance
node_storage -->|"journals writes"| node_wal
node_storage -->|"maintains projection"| node_projection
node_storage -.->|"supports sync"| node_crdt
node_storage -->|"retrieves context"| node_context
node_obsidian -->|"queries and writes"| node_rest_server
node_mobile_app -->|"uses binding"| node_mobile_sdk
node_studio -->|"connects to backend"| node_storage

click node_node_binding "https://github.com/freshair129/genesisblock/blob/main/index.js"
click node_rest_server "https://github.com/freshair129/genesisblock/blob/main/src/main.rs"
click node_rest_router "https://github.com/freshair129/genesisblock/blob/main/src/router.rs"
click node_mcp "https://github.com/freshair129/genesisblock/blob/main/mcp/server.js"
click node_go_sdk "https://github.com/freshair129/genesisblock/blob/main/genesisdb-go/client.go"
click node_python_sdk "https://github.com/freshair129/genesisblock/blob/main/genesisdb-python/genesisdb/client.py"
click node_mobile_sdk "https://github.com/freshair129/genesisblock/blob/main/react-native-genesisdb/src/index.ts"
click node_query_api "https://github.com/freshair129/genesisblock/blob/main/src/query/mod.rs"
click node_query_ast "https://github.com/freshair129/genesisblock/blob/main/src/query/ast.rs"
click node_context "https://github.com/freshair129/genesisblock/blob/main/src/lib.rs"
click node_storage "https://github.com/freshair129/genesisblock/blob/main/src/lib.rs"
click node_graph "https://github.com/freshair129/genesisblock/blob/main/src/lib.rs"
click node_vectors "https://github.com/freshair129/genesisblock/blob/main/src/lib.rs"
click node_temporal "https://github.com/freshair129/genesisblock/blob/main/src/lib.rs"
click node_provenance "https://github.com/freshair129/genesisblock/blob/main/src/lib.rs"
click node_wal "https://github.com/freshair129/genesisblock/blob/main/src/lib.rs"
click node_projection "https://github.com/freshair129/genesisblock/blob/main/src/lib.rs"
click node_crdt "https://github.com/freshair129/genesisblock/blob/main/src/lib.rs"
click node_obsidian "https://github.com/freshair129/genesisblock/blob/main/obsidian-plugin/main.ts"
click node_mobile_app "https://github.com/freshair129/genesisblock/blob/main/genesisblock-mobile/src/App.tsx"
click node_studio "https://github.com/freshair129/genesisblock/blob/main/studio/src/App.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_binding,node_rest_server,node_rest_router,node_mcp,node_go_sdk,node_python_sdk,node_mobile_sdk toneBlue
class node_query_api,node_query_ast,node_context toneAmber
class node_storage,node_graph,node_vectors,node_temporal,node_provenance toneMint
class node_wal,node_projection,node_crdt toneRose
class node_obsidian,node_mobile_app,node_studio,node_app_user toneIndigo
```

## Components

### Access interfaces

- [Node binding](https://github.com/freshair129/genesisblock/blob/main/index.js): `index.js`
- [REST server](https://github.com/freshair129/genesisblock/blob/main/src/main.rs): `src/main.rs`
- [REST router](https://github.com/freshair129/genesisblock/blob/main/src/router.rs): `src/router.rs`
- [MCP server](https://github.com/freshair129/genesisblock/blob/main/mcp/server.js): `mcp/server.js`
- [Go SDK](https://github.com/freshair129/genesisblock/blob/main/genesisdb-go/client.go): `genesisdb-go/client.go`
- [Python SDK](https://github.com/freshair129/genesisblock/blob/main/genesisdb-python/genesisdb/client.py): `genesisdb-python/genesisdb/client.py`
- [Mobile bindings](https://github.com/freshair129/genesisblock/blob/main/react-native-genesisdb/src/index.ts): `react-native-genesisdb/src/index.ts`

### Query and retrieval

- [HQL and Query IR](https://github.com/freshair129/genesisblock/blob/main/src/query/mod.rs): `src/query/mod.rs`
- [Query AST](https://github.com/freshair129/genesisblock/blob/main/src/query/ast.rs): `src/query/ast.rs`
- [Tiered context](https://github.com/freshair129/genesisblock/blob/main/src/lib.rs): `src/lib.rs`

### Database engine

- [Storage engine](https://github.com/freshair129/genesisblock/blob/main/src/lib.rs): `src/lib.rs`
- [Property graph](https://github.com/freshair129/genesisblock/blob/main/src/lib.rs): `src/lib.rs`
- [Vector search](https://github.com/freshair129/genesisblock/blob/main/src/lib.rs): `src/lib.rs`
- [Temporal history](https://github.com/freshair129/genesisblock/blob/main/src/lib.rs): `src/lib.rs`
- [Provenance primitives](https://github.com/freshair129/genesisblock/blob/main/src/lib.rs): `src/lib.rs`

### Durable state

- [WAL and recovery](https://github.com/freshair129/genesisblock/blob/main/src/lib.rs): `src/lib.rs`
- [SQLite projection](https://github.com/freshair129/genesisblock/blob/main/src/lib.rs): `src/lib.rs`
- [CRDT synchronization](https://github.com/freshair129/genesisblock/blob/main/src/lib.rs): `src/lib.rs`

### Client applications

- [Obsidian plugin](https://github.com/freshair129/genesisblock/blob/main/obsidian-plugin/main.ts): `obsidian-plugin/main.ts`
- [Mobile app](https://github.com/freshair129/genesisblock/blob/main/genesisblock-mobile/src/App.tsx): `genesisblock-mobile/src/App.tsx`
- [Studio graph explorer](https://github.com/freshair129/genesisblock/blob/main/studio/src/App.tsx): `studio/src/App.tsx`

### Other components

- **Application or agent**

## Connections

- Application or agent → Node binding: opens embedded
- Application or agent → REST server: sends requests
- Application or agent → MCP server: invokes tools
- Application or agent → Go SDK: uses SDK
- Application or agent → Python SDK: uses SDK
- Node binding → Storage engine: calls engine
- REST server → Storage engine: opens store
- REST server → REST router: builds router
- REST router → Storage engine: dispatches operations
- REST router → HQL and Query IR: dispatches queries
- MCP server → Node binding: opens database
- Go SDK → REST server: HTTP requests
- Python SDK → REST server: HTTP requests
- Mobile bindings → REST server: connects to API
- HQL and Query IR → Query AST: parses queries
- HQL and Query IR → Storage engine: executes queries
- Storage engine → Property graph: manages graph
- Storage engine → Vector search: indexes vectors
- Storage engine → Temporal history: records history
- Storage engine → Provenance primitives: supports provenance
- Storage engine → WAL and recovery: journals writes
- Storage engine → SQLite projection: maintains projection
- Storage engine → CRDT synchronization: supports sync
- Storage engine → Tiered context: retrieves context
- Obsidian plugin → REST server: queries and writes
- Mobile app → Mobile bindings: uses binding
- Studio graph explorer → Storage engine: connects to backend