# vacterro/saipen architecture

> Architecture diagram of the GitHub repository vacterro/saipen, 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/vacterro/saipen
- Repository: https://github.com/vacterro/saipen

## Overview

SAIPEN is a local, file-backed continuation protocol for AI coding agents. The principal workflow is to invoke continue, resolve the project’s persisted state and next action, resume work, and checkpoint the result through journaled operations that are validated before and after mutation. Plain project files preserve state, task history, and durable knowledge across sessions. The README also describes optional autonomous maintenance and goal/subagent modes, plus host installation and a canonical validator. Several internal links are based on README statements or SOURCE INDEX references; unsampled behavior is not inferred.

Main entry points: [`tools/saipen_engine/operations.py`](https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/operations.py) (State operations), [`tools/saipen_engine/router.py`](https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/router.py) (Action router), [`tools/saipen.py`](https://github.com/vacterro/saipen/blob/main/tools/saipen.py) (SAIPEN CLI), [`tools/saipen_engine/fast_check.py`](https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/fast_check.py) (Mutation checks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Continuation workflow"]
  node_cli["SAIPEN CLI<br/>[saipen.py]"]
  node_router["Action router<br/>[router.py]"]
  node_operations["State operations<br/>[operations.py]"]
  node_context["Context compiler<br/>[context.py]"]
end

subgraph group_state["Project state"]
  node_statefiles["Project memory files<br/>[paths.py]"]
  node_board["Ticket board<br/>[board.py]"]
  node_stateparse["State parser<br/>[state.py]"]
  node_eventlog["Event history<br/>[log.py]"]
  node_knowledge["Durable knowledge<br/>[context.py]"]
  node_intake["Source intake<br/>[intake.py]"]
end

subgraph group_integrity["Integrity checks"]
  node_journal["Write-ahead journal<br/>[journal.py]"]
  node_codec["Document codec<br/>[codec.py]"]
  node_fastcheck["Mutation checks<br/>[fast_check.py]"]
  node_validator["Canonical validator<br/>[validate.py]"]
  node_freshness["Freshness identity<br/>[freshness.py]"]
end

subgraph group_extensions["Optional extensions"]
  node_maintenance["Autonomous maintenance<br/>[improve.py]"]
  node_crew["Crew execution<br/>[crew.py]"]
  node_hostinstall["Host integration<br/>[autoinject.py]"]
  node_opencode["OpenCode guard<br/>[saipen-guard.js]"]
end

node_operator(("Operator / agent"))

node_operator -->|"invokes"| node_cli
node_cli -->|"routes actions"| node_router
node_cli -->|"runs operations"| node_operations
node_router -->|"reads state"| node_stateparse
node_router -->|"reads tickets"| node_board
node_context -->|"uses routing"| node_router
node_context -->|"loads relevant facts"| node_knowledge
node_operations -->|"journals mutations"| node_journal
node_operations -->|"checks proposals"| node_fastcheck
node_operations -->|"writes checkpoints"| node_statefiles
node_operations -->|"records events"| node_eventlog
node_journal -->|"preserves bytes"| node_codec
node_fastcheck -->|"validates state"| node_stateparse
node_fastcheck -->|"validates tickets"| node_board
node_validator -->|"validates checkpoints"| node_statefiles
node_validator -->|"checks freshness"| node_freshness
node_operations -->|"captures source"| node_intake
node_maintenance -->|"uses journal"| node_journal
node_crew -->|"gates convergence"| node_validator
node_operator -->|"installs locally"| node_hostinstall
node_hostinstall -.->|"supports host"| node_opencode
node_maintenance -.->|"evolves project"| node_operations
node_operator -.->|"opts into execution"| node_crew

click node_cli "https://github.com/vacterro/saipen/blob/main/tools/saipen.py"
click node_router "https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/router.py"
click node_operations "https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/operations.py"
click node_context "https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/context.py"
click node_statefiles "https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/paths.py"
click node_board "https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/board.py"
click node_stateparse "https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/state.py"
click node_eventlog "https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/log.py"
click node_knowledge "https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/context.py"
click node_intake "https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/intake.py"
click node_journal "https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/journal.py"
click node_codec "https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/codec.py"
click node_fastcheck "https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/fast_check.py"
click node_validator "https://github.com/vacterro/saipen/blob/main/tools/validate.py"
click node_freshness "https://github.com/vacterro/saipen/blob/main/tools/freshness.py"
click node_maintenance "https://github.com/vacterro/saipen/blob/main/tools/improve.py"
click node_crew "https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/crew.py"
click node_hostinstall "https://github.com/vacterro/saipen/blob/main/tools/autoinject.py"
click node_opencode "https://github.com/vacterro/saipen/blob/main/extensions/adapters/opencode/saipen-guard.js"

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_router,node_operations,node_context toneBlue
class node_statefiles,node_board,node_stateparse,node_eventlog,node_knowledge,node_intake toneAmber
class node_journal,node_codec,node_fastcheck,node_validator,node_freshness toneMint
class node_maintenance,node_crew,node_hostinstall,node_opencode toneRose
class node_operator toneIndigo
```

## Components

### Continuation workflow

- [SAIPEN CLI](https://github.com/vacterro/saipen/blob/main/tools/saipen.py): `tools/saipen.py`
- [Action router](https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/router.py): `tools/saipen_engine/router.py`
- [State operations](https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/operations.py): `tools/saipen_engine/operations.py`
- [Context compiler](https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/context.py): `tools/saipen_engine/context.py`

### Project state

- [Project memory files](https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/paths.py): `tools/saipen_engine/paths.py`
- [Ticket board](https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/board.py): `tools/saipen_engine/board.py`
- [State parser](https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/state.py): `tools/saipen_engine/state.py`
- [Event history](https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/log.py): `tools/saipen_engine/log.py`
- [Durable knowledge](https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/context.py): `tools/saipen_engine/context.py`
- [Source intake](https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/intake.py): `tools/saipen_engine/intake.py`

### Integrity checks

- [Write-ahead journal](https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/journal.py): `tools/saipen_engine/journal.py`
- [Document codec](https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/codec.py): `tools/saipen_engine/codec.py`
- [Mutation checks](https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/fast_check.py): `tools/saipen_engine/fast_check.py`
- [Canonical validator](https://github.com/vacterro/saipen/blob/main/tools/validate.py): `tools/validate.py`
- [Freshness identity](https://github.com/vacterro/saipen/blob/main/tools/freshness.py): `tools/freshness.py`

### Optional extensions

- [Autonomous maintenance](https://github.com/vacterro/saipen/blob/main/tools/improve.py): `tools/improve.py`
- [Crew execution](https://github.com/vacterro/saipen/blob/main/tools/saipen_engine/crew.py): `tools/saipen_engine/crew.py`
- [Host integration](https://github.com/vacterro/saipen/blob/main/tools/autoinject.py): `tools/autoinject.py`
- [OpenCode guard](https://github.com/vacterro/saipen/blob/main/extensions/adapters/opencode/saipen-guard.js): `extensions/adapters/opencode/saipen-guard.js`

### Other components

- **Operator / agent**

## Connections

- Operator / agent → SAIPEN CLI: invokes (evidence: `README.md`)
- SAIPEN CLI → Action router: routes actions (evidence: `tools/saipen.py`)
- SAIPEN CLI → State operations: runs operations (evidence: `README.md`)
- Action router → State parser: reads state (evidence: `tools/saipen_engine/router.py`)
- Action router → Ticket board: reads tickets (evidence: `tools/saipen_engine/router.py`)
- Context compiler → Action router: uses routing (evidence: `tools/saipen_engine/router.py`)
- Context compiler → Durable knowledge: loads relevant facts (evidence: `README.md`)
- State operations → Write-ahead journal: journals mutations (evidence: `tools/saipen_engine/journal.py`)
- State operations → Mutation checks: checks proposals (evidence: `tools/saipen_engine/fast_check.py`)
- State operations → Project memory files: writes checkpoints (evidence: `README.md`)
- State operations → Event history: records events (evidence: `tools/saipen_engine/operations.py`)
- Write-ahead journal → Document codec: preserves bytes (evidence: `tools/saipen_engine/journal.py`)
- Mutation checks → State parser: validates state (evidence: `tools/saipen_engine/fast_check.py`)
- Mutation checks → Ticket board: validates tickets (evidence: `tools/saipen_engine/fast_check.py`)
- Canonical validator → Project memory files: validates checkpoints (evidence: `README.md`)
- Canonical validator → Freshness identity: checks freshness
- State operations → Source intake: captures source (evidence: `tools/saipen_engine/operations.py`)
- Autonomous maintenance → Write-ahead journal: uses journal (evidence: `tools/improve.py`)
- Crew execution → Canonical validator: gates convergence
- Operator / agent → Host integration: installs locally (evidence: `README.md`)
- Host integration → OpenCode guard: supports host
- Autonomous maintenance → State operations: evolves project
- Operator / agent → Crew execution: opts into execution (evidence: `README.md`)
