# benjaminveysi/yowza architecture

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

- Interactive diagram: https://gitdiagram.com/benjaminveysi/yowza
- Repository: https://github.com/benjaminveysi/yowza

## Overview

Yowza is an offline-first persistent data engine with a C storage/database core and Go host. Its principal workflow accepts client operations through the daemon, authenticates them, applies writes through Raft when clustered, and serves reads from the database; its separate developer-mode workflow hosts a Wasm database behind a framework HTTP engine with cloud bootstrap. Query parsing, verified plans, the custom ISA, and the C execution engine form an internal query layer. The README documents WAL recovery, Timeline versioning, indexing, and optional clustering; several of those implementations were not sampled, so links without direct evidence are omitted.

Main entry points: [`include/segdb.h`](https://github.com/benjaminveysi/yowza/blob/main/include/segdb.h) (Layered SegDB), [`cmd/yowza/main.go`](https://github.com/benjaminveysi/yowza/blob/main/cmd/yowza/main.go) (Developer host), [`cmd/yowzad/main.go`](https://github.com/benjaminveysi/yowza/blob/main/cmd/yowzad/main.go) (Authenticated daemon), [`src/query_isa.c`](https://github.com/benjaminveysi/yowza/blob/main/src/query_isa.c) (Query ISA)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Applications and access"]
  node_client["CLI client<br/>[main.go]"]
  node_daemon["Authenticated daemon<br/>[main.go]"]
  node_devhost["Developer host<br/>[main.go]"]
  node_framework["Webhook framework<br/>[framework.go]"]
end

subgraph group_query["Query execution"]
  node_querylang["YowzaQL parser<br/>[parser.go]"]
  node_queryengine["Query planner<br/>[engine.go]"]
  node_queryisa["Query ISA<br/>[query_isa.c]"]
  node_querycontract["ISA contract<br/>[query_isa.h]"]
  node_wasm["Wasm runtime<br/>[runtime.go]"]
end

subgraph group_storage["Database and durability"]
  node_dbapi["Go database host<br/>[yowza.go]"]
  node_segdb["Layered SegDB<br/>[segdb.h]"]
  node_coreinterfaces["C core interfaces"]
  node_storagev2["64-bit object storage<br/>[storage2.c]"]
  node_waldrivers["WAL drivers<br/>[storage_memory.c]"]
  node_timeline["Timeline versioning<br/>[timeline.go]"]
end

subgraph group_distributed["Clustering and integrations"]
  node_cloudmanager["Cloud sync manager<br/>[manager.go]"]
  node_cloudbackend["Cloud backends"]
  node_raft["Raft cluster<br/>[raft.go]"]
  node_coord["Raft coordination"]
  node_adapters["Service adapters"]
end

node_user(("API user"))
node_externalservices(("External services"))

node_user -->|"issues commands"| node_client
node_client -->|"sends requests"| node_daemon
node_daemon -->|"reads values"| node_dbapi
node_daemon -.->|"applies writes"| node_raft
node_devhost -->|"creates database"| node_dbapi
node_devhost -->|"bootstraps sync"| node_cloudmanager
node_devhost -->|"creates engine"| node_framework
node_framework -->|"uses manager"| node_cloudmanager
node_querylang -.->|"parses queries"| node_queryengine
node_queryengine -->|"compiles plans"| node_queryisa
node_querycontract -->|"defines encoding"| node_queryisa
node_queryisa -->|"executes against"| node_segdb
node_dbapi -.->|"runs Wasm"| node_wasm
node_segdb -.->|"uses object store"| node_storagev2
node_segdb -.->|"persists WAL"| node_waldrivers
node_segdb -.->|"versions writes"| node_timeline
node_cloudmanager -.->|"syncs state"| node_cloudbackend
node_raft -.->|"coordinates"| node_coord
node_adapters -.->|"connects optionally"| node_externalservices

click node_client "https://github.com/benjaminveysi/yowza/blob/main/cmd/yowzactl/main.go"
click node_daemon "https://github.com/benjaminveysi/yowza/blob/main/cmd/yowzad/main.go"
click node_devhost "https://github.com/benjaminveysi/yowza/blob/main/cmd/yowza/main.go"
click node_framework "https://github.com/benjaminveysi/yowza/blob/main/framework/framework.go"
click node_querylang "https://github.com/benjaminveysi/yowza/blob/main/query/parser.go"
click node_queryengine "https://github.com/benjaminveysi/yowza/blob/main/query/engine.go"
click node_queryisa "https://github.com/benjaminveysi/yowza/blob/main/src/query_isa.c"
click node_querycontract "https://github.com/benjaminveysi/yowza/blob/main/include/query_isa.h"
click node_wasm "https://github.com/benjaminveysi/yowza/blob/main/third_party_wazero64/runtime.go"
click node_dbapi "https://github.com/benjaminveysi/yowza/blob/main/yowza.go"
click node_segdb "https://github.com/benjaminveysi/yowza/blob/main/include/segdb.h"
click node_coreinterfaces "https://github.com/benjaminveysi/yowza/tree/main/include"
click node_storagev2 "https://github.com/benjaminveysi/yowza/blob/main/src/storage2.c"
click node_waldrivers "https://github.com/benjaminveysi/yowza/blob/main/src/storage_memory.c"
click node_timeline "https://github.com/benjaminveysi/yowza/blob/main/timeline.go"
click node_cloudmanager "https://github.com/benjaminveysi/yowza/blob/main/cloud/manager.go"
click node_cloudbackend "https://github.com/benjaminveysi/yowza/tree/main/cloud"
click node_raft "https://github.com/benjaminveysi/yowza/blob/main/cluster/raft.go"
click node_coord "https://github.com/benjaminveysi/yowza/blob/main/coord_coordinator.go"
click node_adapters "https://github.com/benjaminveysi/yowza/tree/main/adapters"

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_client,node_daemon,node_devhost,node_framework,node_user toneBlue
class node_querylang,node_queryengine,node_queryisa,node_querycontract,node_wasm toneAmber
class node_dbapi,node_segdb,node_coreinterfaces,node_storagev2,node_waldrivers,node_timeline toneMint
class node_cloudmanager,node_cloudbackend,node_raft,node_coord,node_adapters toneRose
class node_externalservices toneIndigo
```

## Components

### Applications and access

- [CLI client](https://github.com/benjaminveysi/yowza/blob/main/cmd/yowzactl/main.go): `cmd/yowzactl/main.go`
- [Authenticated daemon](https://github.com/benjaminveysi/yowza/blob/main/cmd/yowzad/main.go): `cmd/yowzad/main.go`
- [Developer host](https://github.com/benjaminveysi/yowza/blob/main/cmd/yowza/main.go): `cmd/yowza/main.go`
- [Webhook framework](https://github.com/benjaminveysi/yowza/blob/main/framework/framework.go): `framework/framework.go`

### Query execution

- [YowzaQL parser](https://github.com/benjaminveysi/yowza/blob/main/query/parser.go): `query/parser.go`
- [Query planner](https://github.com/benjaminveysi/yowza/blob/main/query/engine.go): `query/engine.go`
- [Query ISA](https://github.com/benjaminveysi/yowza/blob/main/src/query_isa.c): `src/query_isa.c`
- [ISA contract](https://github.com/benjaminveysi/yowza/blob/main/include/query_isa.h): `include/query_isa.h`
- [Wasm runtime](https://github.com/benjaminveysi/yowza/blob/main/third_party_wazero64/runtime.go): `third_party_wazero64/runtime.go`

### Database and durability

- [Go database host](https://github.com/benjaminveysi/yowza/blob/main/yowza.go): `yowza.go`
- [Layered SegDB](https://github.com/benjaminveysi/yowza/blob/main/include/segdb.h): `include/segdb.h`
- [C core interfaces](https://github.com/benjaminveysi/yowza/tree/main/include): `include`
- [64-bit object storage](https://github.com/benjaminveysi/yowza/blob/main/src/storage2.c): `src/storage2.c`
- [WAL drivers](https://github.com/benjaminveysi/yowza/blob/main/src/storage_memory.c): `src/storage_memory.c`
- [Timeline versioning](https://github.com/benjaminveysi/yowza/blob/main/timeline.go): `timeline.go`

### Clustering and integrations

- [Cloud sync manager](https://github.com/benjaminveysi/yowza/blob/main/cloud/manager.go): `cloud/manager.go`
- [Cloud backends](https://github.com/benjaminveysi/yowza/tree/main/cloud): `cloud`
- [Raft cluster](https://github.com/benjaminveysi/yowza/blob/main/cluster/raft.go): `cluster/raft.go`
- [Raft coordination](https://github.com/benjaminveysi/yowza/blob/main/coord_coordinator.go): `coord_coordinator.go`
- [Service adapters](https://github.com/benjaminveysi/yowza/tree/main/adapters): `adapters`

### Other components

- **API user**
- **External services**

## Connections

- API user → CLI client: issues commands (evidence: `cmd/yowzactl/main.go`)
- CLI client → Authenticated daemon: sends requests (evidence: `cmd/yowzactl/main.go`)
- Authenticated daemon → Go database host: reads values (evidence: `cmd/yowzad/main.go`)
- Authenticated daemon → Raft cluster: applies writes
- Developer host → Go database host: creates database (evidence: `cmd/yowza/main.go`)
- Developer host → Cloud sync manager: bootstraps sync (evidence: `cmd/yowza/main.go`)
- Developer host → Webhook framework: creates engine (evidence: `cmd/yowza/main.go`)
- Webhook framework → Cloud sync manager: uses manager (evidence: `framework/framework.go`)
- YowzaQL parser → Query planner: parses queries
- Query planner → Query ISA: compiles plans
- ISA contract → Query ISA: defines encoding (evidence: `include/query_isa.h`)
- Query ISA → Layered SegDB: executes against (evidence: `src/query_isa.c`)
- Go database host → Wasm runtime: runs Wasm
- Layered SegDB → 64-bit object storage: uses object store
- Layered SegDB → WAL drivers: persists WAL
- Layered SegDB → Timeline versioning: versions writes
- Cloud sync manager → Cloud backends: syncs state
- Raft cluster → Raft coordination: coordinates
- Service adapters → External services: connects optionally
