# dagztagz/vesper-runtime architecture

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

- Interactive diagram: https://gitdiagram.com/dagztagz/vesper-runtime
- Repository: https://github.com/dagztagz/vesper-runtime

## Overview

Vesper is an offline, local-first command-line runtime for maintaining structured notes and producing verifiable signed snapshots. The main workflow is: initialize a workspace, check or heal its schema, maintain and age memory, create a signed fork, verify the fork or workspace head, and optionally export an audit folder. The CLI dispatches these operations; the schema, memory, fork, cryptography, export, and filesystem-safety modules implement the domain stages. Relationships below are limited to visible CLI dispatches, SOURCE INDEX references, and README-documented behavior; unsampled implementation details are not inferred.

Main entry points: [`src/vesper/cli.py`](https://github.com/dagztagz/vesper-runtime/blob/main/src/vesper/cli.py) (CLI dispatcher), [`src/vesper/export.py`](https://github.com/dagztagz/vesper-runtime/blob/main/src/vesper/export.py) (Audit export), [`src/vesper/fork.py`](https://github.com/dagztagz/vesper-runtime/blob/main/src/vesper/fork.py) (Signed forks), [`src/vesper/paths.py`](https://github.com/dagztagz/vesper-runtime/blob/main/src/vesper/paths.py) (Workspace path safety)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Command interface"]
  node_cli["CLI dispatcher<br/>[cli.py]"]
end

subgraph group_domain["Notes and snapshots"]
  node_schema["Schema check/heal<br/>[schema.py]"]
  node_memory["Memory lifecycle<br/>[memory.py]"]
  node_forks["Signed forks<br/>[fork.py]"]
end

subgraph group_trust["Integrity and audit"]
  node_crypto["Key and signatures<br/>[crypto.py]"]
  node_audit["Audit export<br/>[export.py]"]
end

subgraph group_runtime["Workspace foundations"]
  node_paths["Workspace path safety<br/>[paths.py]"]
  node_errors["Runtime errors<br/>[errors.py]"]
end

node_user(("Terminal user"))
node_workspace[("Local workspace files")]
node_audit_folder["Audit folder"]

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches schema"| node_schema
node_cli -->|"dispatches memory"| node_memory
node_cli -->|"dispatches fork/verify"| node_forks
node_cli -->|"dispatches export"| node_audit
node_cli -->|"resolves workspace"| node_paths
node_cli -->|"maps failures"| node_errors
node_schema -->|"raises validation"| node_errors
node_memory -->|"raises validation"| node_errors
node_forks -->|"signs and verifies"| node_crypto
node_forks -->|"uses memory state"| node_memory
node_forks -->|"uses workspace paths"| node_paths
node_crypto -->|"uses key paths"| node_paths
node_audit -->|"checks fork head"| node_forks
node_audit -->|"checks key security"| node_crypto
node_audit -->|"checks memory decay"| node_memory
node_audit -->|"checks schema"| node_schema
node_audit -->|"checks path safety"| node_paths
node_paths -->|"jails file access"| node_workspace
node_forks -->|"reads and writes state"| node_workspace
node_crypto -->|"stores key material"| node_workspace
node_audit -->|"writes audit record"| node_audit_folder

click node_cli "https://github.com/dagztagz/vesper-runtime/blob/main/src/vesper/cli.py"
click node_schema "https://github.com/dagztagz/vesper-runtime/blob/main/src/vesper/schema.py"
click node_memory "https://github.com/dagztagz/vesper-runtime/blob/main/src/vesper/memory.py"
click node_forks "https://github.com/dagztagz/vesper-runtime/blob/main/src/vesper/fork.py"
click node_crypto "https://github.com/dagztagz/vesper-runtime/blob/main/src/vesper/crypto.py"
click node_audit "https://github.com/dagztagz/vesper-runtime/blob/main/src/vesper/export.py"
click node_paths "https://github.com/dagztagz/vesper-runtime/blob/main/src/vesper/paths.py"
click node_errors "https://github.com/dagztagz/vesper-runtime/blob/main/src/vesper/errors.py"

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_cli,node_user toneBlue
class node_schema,node_memory,node_forks,node_workspace toneAmber
class node_crypto,node_audit toneMint
class node_paths,node_errors toneRose
class node_audit_folder toneIndigo
```

## Components

### Command interface

- [CLI dispatcher](https://github.com/dagztagz/vesper-runtime/blob/main/src/vesper/cli.py): `src/vesper/cli.py`

### Notes and snapshots

- [Schema check/heal](https://github.com/dagztagz/vesper-runtime/blob/main/src/vesper/schema.py): `src/vesper/schema.py`
- [Memory lifecycle](https://github.com/dagztagz/vesper-runtime/blob/main/src/vesper/memory.py): `src/vesper/memory.py`
- [Signed forks](https://github.com/dagztagz/vesper-runtime/blob/main/src/vesper/fork.py): `src/vesper/fork.py`

### Integrity and audit

- [Key and signatures](https://github.com/dagztagz/vesper-runtime/blob/main/src/vesper/crypto.py): `src/vesper/crypto.py`
- [Audit export](https://github.com/dagztagz/vesper-runtime/blob/main/src/vesper/export.py): `src/vesper/export.py`

### Workspace foundations

- [Workspace path safety](https://github.com/dagztagz/vesper-runtime/blob/main/src/vesper/paths.py): `src/vesper/paths.py`
- [Runtime errors](https://github.com/dagztagz/vesper-runtime/blob/main/src/vesper/errors.py): `src/vesper/errors.py`

### Other components

- **Terminal user**
- **Local workspace files**
- **Audit folder**

## Connections

- Terminal user → CLI dispatcher: runs commands (evidence: `README.md`)
- CLI dispatcher → Schema check/heal: dispatches schema (evidence: `src/vesper/cli.py`)
- CLI dispatcher → Memory lifecycle: dispatches memory (evidence: `src/vesper/cli.py`)
- CLI dispatcher → Signed forks: dispatches fork/verify (evidence: `src/vesper/cli.py`)
- CLI dispatcher → Audit export: dispatches export (evidence: `src/vesper/cli.py`)
- CLI dispatcher → Workspace path safety: resolves workspace (evidence: `src/vesper/cli.py`)
- CLI dispatcher → Runtime errors: maps failures (evidence: `src/vesper/cli.py`)
- Schema check/heal → Runtime errors: raises validation (evidence: `src/vesper/schema.py`)
- Memory lifecycle → Runtime errors: raises validation (evidence: `src/vesper/memory.py`)
- Signed forks → Key and signatures: signs and verifies (evidence: `src/vesper/fork.py`)
- Signed forks → Memory lifecycle: uses memory state (evidence: `src/vesper/fork.py`)
- Signed forks → Workspace path safety: uses workspace paths (evidence: `src/vesper/fork.py`)
- Key and signatures → Workspace path safety: uses key paths (evidence: `src/vesper/crypto.py`)
- Audit export → Signed forks: checks fork head (evidence: `src/vesper/export.py`)
- Audit export → Key and signatures: checks key security (evidence: `src/vesper/export.py`)
- Audit export → Memory lifecycle: checks memory decay (evidence: `src/vesper/export.py`)
- Audit export → Schema check/heal: checks schema (evidence: `src/vesper/export.py`)
- Audit export → Workspace path safety: checks path safety (evidence: `src/vesper/export.py`)
- Workspace path safety → Local workspace files: jails file access (evidence: `src/vesper/paths.py`)
- Signed forks → Local workspace files: reads and writes state (evidence: `README.md`)
- Key and signatures → Local workspace files: stores key material (evidence: `README.md`)
- Audit export → Audit folder: writes audit record (evidence: `README.md`)
