# davyjones7321/jev-state-engine architecture

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

- Interactive diagram: https://gitdiagram.com/davyjones7321/jev-state-engine
- Repository: https://github.com/davyjones7321/jev-state-engine

## Overview

Jev State Engine takes a task ticket, investigates the target repository, plans scoped subgoals, implements them, and gates each change before committing or retrying. After the plan is exhausted, it performs final verification and either completes or escalates. The CLI wires the engine to a workspace, an LLM, and the Jev Gatekeeper; the engine persists resumable state and strike counters in SQLite. The README documents the workflow and limitations; sampled excerpts confirm workspace checks and Gatekeeper API behavior, while some engine orchestration details are unsampled.

Main entry points: [`src/jev/engine.py`](https://github.com/davyjones7321/jev-state-engine/blob/master/src/jev/engine.py) (Jev engine), [`src/jev/workspace.py`](https://github.com/davyjones7321/jev-state-engine/blob/master/src/jev/workspace.py) (Workspace operations), [`src/main.py`](https://github.com/davyjones7321/jev-state-engine/blob/master/src/main.py) (CLI entry), [`src/jev/gatekeeper.py`](https://github.com/davyjones7321/jev-state-engine/blob/master/src/jev/gatekeeper.py) (Jev Gatekeeper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Task workflow"]
  node_investigate["Investigation<br/>[engine.py]"]
  node_plan["Subgoal planning<br/>[engine.py]"]
  node_implement["Subgoal implementation<br/>[engine.py]"]
end

subgraph group_runtime["Engine runtime"]
  node_cli["CLI entry<br/>[main.py]"]
  node_engine["Jev engine<br/>[engine.py]"]
  node_state_models["State models<br/>[models.py]"]
end

subgraph group_repo["Repository changes"]
  node_workspace["Workspace operations<br/>[workspace.py]"]
end

subgraph group_validation["Validation services"]
  node_gate["Subgoal gate<br/>[engine.py]"]
  node_final["Final verification<br/>[engine.py]"]
  node_gatekeeper["Jev Gatekeeper<br/>[gatekeeper.py]"]
end

node_user(("Ticket requester"))
node_gemini(("Gemini LLM"))
node_jev_api(("Jev System One API"))
node_target_repo[("Target Git repository")]
node_checkpoint_db[("SQLite checkpoints")]
node_escalation_log["Escalation log"]

node_user -->|"submits ticket"| node_cli
node_cli -->|"executes run"| node_engine
node_cli -->|"configures workspace"| node_workspace
node_cli -->|"configures gate"| node_gatekeeper
node_cli -.->|"configures LLM"| node_gemini
node_engine -->|"dispatches phase"| node_investigate
node_engine -->|"dispatches phase"| node_plan
node_engine -->|"dispatches phase"| node_implement
node_engine -->|"dispatches gate"| node_gate
node_engine -->|"dispatches verification"| node_final
node_investigate -->|"requests exploration"| node_gemini
node_investigate -->|"reads repository"| node_workspace
node_plan -->|"requests plan"| node_gemini
node_implement -->|"requests code"| node_gemini
node_implement -->|"writes scoped changes"| node_workspace
node_gate -->|"runs mechanical checks"| node_workspace
node_gate -->|"requests semantic verdict"| node_gatekeeper
node_gatekeeper -->|"posts validation"| node_jev_api
node_final -->|"collects final diff"| node_workspace
node_final -->|"requests ticket verification"| node_gatekeeper
node_workspace -->|"reads and changes"| node_target_repo
node_workspace -->|"commits or rolls back"| node_target_repo
node_engine -->|"persists run state"| node_checkpoint_db
node_engine -->|"records escalation"| node_escalation_log
node_engine -->|"uses typed state"| node_state_models
node_gatekeeper -->|"uses verdict models"| node_state_models

click node_cli "https://github.com/davyjones7321/jev-state-engine/blob/master/src/main.py"
click node_engine "https://github.com/davyjones7321/jev-state-engine/blob/master/src/jev/engine.py"
click node_investigate "https://github.com/davyjones7321/jev-state-engine/blob/master/src/jev/engine.py"
click node_plan "https://github.com/davyjones7321/jev-state-engine/blob/master/src/jev/engine.py"
click node_implement "https://github.com/davyjones7321/jev-state-engine/blob/master/src/jev/engine.py"
click node_gate "https://github.com/davyjones7321/jev-state-engine/blob/master/src/jev/engine.py"
click node_final "https://github.com/davyjones7321/jev-state-engine/blob/master/src/jev/engine.py"
click node_workspace "https://github.com/davyjones7321/jev-state-engine/blob/master/src/jev/workspace.py"
click node_gatekeeper "https://github.com/davyjones7321/jev-state-engine/blob/master/src/jev/gatekeeper.py"
click node_state_models "https://github.com/davyjones7321/jev-state-engine/blob/master/src/jev/models.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_investigate,node_plan,node_implement toneBlue
class node_cli,node_engine,node_state_models,node_target_repo,node_checkpoint_db toneAmber
class node_workspace,node_user,node_jev_api toneMint
class node_gate,node_final,node_gatekeeper toneRose
class node_gemini,node_escalation_log toneIndigo
```

## Components

### Task workflow

- [Investigation](https://github.com/davyjones7321/jev-state-engine/blob/master/src/jev/engine.py): `src/jev/engine.py`
- [Subgoal planning](https://github.com/davyjones7321/jev-state-engine/blob/master/src/jev/engine.py): `src/jev/engine.py`
- [Subgoal implementation](https://github.com/davyjones7321/jev-state-engine/blob/master/src/jev/engine.py): `src/jev/engine.py`

### Engine runtime

- [CLI entry](https://github.com/davyjones7321/jev-state-engine/blob/master/src/main.py): `src/main.py`
- [Jev engine](https://github.com/davyjones7321/jev-state-engine/blob/master/src/jev/engine.py): `src/jev/engine.py`
- [State models](https://github.com/davyjones7321/jev-state-engine/blob/master/src/jev/models.py): `src/jev/models.py`

### Repository changes

- [Workspace operations](https://github.com/davyjones7321/jev-state-engine/blob/master/src/jev/workspace.py): `src/jev/workspace.py`

### Validation services

- [Subgoal gate](https://github.com/davyjones7321/jev-state-engine/blob/master/src/jev/engine.py): `src/jev/engine.py`
- [Final verification](https://github.com/davyjones7321/jev-state-engine/blob/master/src/jev/engine.py): `src/jev/engine.py`
- [Jev Gatekeeper](https://github.com/davyjones7321/jev-state-engine/blob/master/src/jev/gatekeeper.py): `src/jev/gatekeeper.py`

### Other components

- **Ticket requester**
- **Gemini LLM**
- **Jev System One API**
- **Target Git repository**
- **SQLite checkpoints**
- **Escalation log**

## Connections

- Ticket requester → CLI entry: submits ticket
- CLI entry → Jev engine: executes run
- CLI entry → Workspace operations: configures workspace
- CLI entry → Jev Gatekeeper: configures gate
- CLI entry → Gemini LLM: configures LLM
- Jev engine → Investigation: dispatches phase
- Jev engine → Subgoal planning: dispatches phase
- Jev engine → Subgoal implementation: dispatches phase
- Jev engine → Subgoal gate: dispatches gate
- Jev engine → Final verification: dispatches verification
- Investigation → Gemini LLM: requests exploration
- Investigation → Workspace operations: reads repository
- Subgoal planning → Gemini LLM: requests plan
- Subgoal implementation → Gemini LLM: requests code
- Subgoal implementation → Workspace operations: writes scoped changes
- Subgoal gate → Workspace operations: runs mechanical checks
- Subgoal gate → Jev Gatekeeper: requests semantic verdict
- Jev Gatekeeper → Jev System One API: posts validation
- Final verification → Workspace operations: collects final diff
- Final verification → Jev Gatekeeper: requests ticket verification
- Workspace operations → Target Git repository: reads and changes
- Workspace operations → Target Git repository: commits or rolls back
- Jev engine → SQLite checkpoints: persists run state
- Jev engine → Escalation log: records escalation
- Jev engine → State models: uses typed state
- Jev Gatekeeper → State models: uses verdict models