# prajwal471/jocky architecture

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

- Interactive diagram: https://gitdiagram.com/prajwal471/jocky
- Repository: https://github.com/prajwal471/jocky

## Overview

JOCKY turns a mission written in its forensic scripting language into a bounded, capability-checked run: the server dispatches it, collectors make read-only observations, and the resulting evidence is persisted as a signed hash chain. Reviewers can inspect missions, evidence, coverage, and evaluation results through the API and dashboard. The README also documents baseline evaluation, active counterfactual measures, equivalence proofs, and citation support. Some subsystem wiring is inferred only from documentation and directory names; uncertain links are omitted.

Main entry points: [`jocky/server/dispatch.py`](https://github.com/prajwal471/jocky/blob/master/jocky/server/dispatch.py) (Mission dispatch), [`jocky/server/api.py`](https://github.com/prajwal471/jocky/blob/master/jocky/server/api.py) (HTTP API), [`jocky/server/db.py`](https://github.com/prajwal471/jocky/blob/master/jocky/server/db.py) (Mission store), [`jocky/eval/harness.py`](https://github.com/prajwal471/jocky/blob/master/jocky/eval/harness.py) (Baseline harness)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["Mission language"]
  node_parser["Mission parser<br/>[parser.py]"]
  node_checker["Safety checker<br/>[checker.py]"]
  node_types["Types and capabilities<br/>[types.py]"]
  node_jir["JIR representation<br/>[jir.py]"]
end

subgraph group_runtime["Collection and evidence"]
  node_interpreter["Mission interpreter<br/>[interpreter.py]"]
  node_builtins["Collector builtins<br/>[builtins.py]"]
  node_harvesters["Host harvesters<br/>[harvesters.py]"]
  node_evidence["Evidence chain<br/>[evidence.py]"]
  node_crypto["Ed25519 signing<br/>[__init__.py]"]
  node_identity["Agent identity<br/>[identity.py]"]
end

subgraph group_service["Server and storage"]
  node_api["HTTP API<br/>[api.py]"]
  node_auth["Token auth<br/>[auth.py]"]
  node_dispatch["Mission dispatch<br/>[dispatch.py]"]
  node_store[("Mission store<br/>[db.py]")]
  node_dashboard["Static dashboard"]
end

subgraph group_review["Review and evaluation"]
  node_coverage["Coverage matrix<br/>[coverage.py]"]
  node_metrics["Interop metrics<br/>[metrics.py]"]
  node_harness["Baseline harness<br/>[harness.py]"]
  node_baselines["Baseline cases<br/>[baselines.py]"]
  node_measures["Active measures<br/>[measures.py]"]
  node_proofs["Equivalence proofs<br/>[equivalence.py]"]
  node_citations["Citation checks<br/>[citation.py]"]
end

subgraph group_operations["Demo operations"]
  node_demo["Demo bootstrap<br/>[bootstrap.py]"]
end

node_operator(("Investigator"))
node_host["Forensic host"]

node_operator -->|"submits missions"| node_api
node_operator -->|"views results"| node_dashboard
node_dashboard -->|"calls routes"| node_api
node_api -->|"checks protected routes"| node_auth
node_api -->|"dispatches missions"| node_dispatch
node_dispatch -->|"parses source"| node_parser
node_parser -->|"checks structure"| node_checker
node_checker -->|"validates capabilities"| node_types
node_parser -->|"serializes program"| node_jir
node_dispatch -->|"runs mission"| node_interpreter
node_interpreter -->|"calls collectors"| node_builtins
node_builtins -->|"reads host data"| node_harvesters
node_harvesters -->|"observes host"| node_host
node_dispatch -->|"records observations"| node_evidence
node_evidence -->|"signs records"| node_crypto
node_evidence -->|"uses agent identity"| node_identity
node_dispatch -->|"persists runs"| node_store
node_api -->|"reads mission data"| node_store
node_dispatch -->|"seeds coverage"| node_coverage
node_api -->|"serves interop metrics"| node_metrics
node_harness -->|"runs cases"| node_baselines
node_harness -->|"executes missions"| node_dispatch
node_harness -->|"checks invariants"| node_proofs
node_harness -->|"reads evaluation records"| node_store
node_measures -->|"tests refusals"| node_dispatch
node_measures -->|"checks persisted evidence"| node_store
node_citations -.->|"checks citations"| node_store
node_demo -->|"seeds coverage"| node_coverage
node_demo -->|"starts server"| node_api

click node_api "https://github.com/prajwal471/jocky/blob/master/jocky/server/api.py"
click node_auth "https://github.com/prajwal471/jocky/blob/master/jocky/server/auth.py"
click node_dispatch "https://github.com/prajwal471/jocky/blob/master/jocky/server/dispatch.py"
click node_store "https://github.com/prajwal471/jocky/blob/master/jocky/server/db.py"
click node_coverage "https://github.com/prajwal471/jocky/blob/master/jocky/server/coverage.py"
click node_metrics "https://github.com/prajwal471/jocky/blob/master/jocky/server/metrics.py"
click node_parser "https://github.com/prajwal471/jocky/blob/master/jocky/dsl/parser.py"
click node_checker "https://github.com/prajwal471/jocky/blob/master/jocky/dsl/checker.py"
click node_types "https://github.com/prajwal471/jocky/blob/master/jocky/dsl/types.py"
click node_jir "https://github.com/prajwal471/jocky/blob/master/jocky/dsl/jir.py"
click node_interpreter "https://github.com/prajwal471/jocky/blob/master/jocky/runtime/interpreter.py"
click node_builtins "https://github.com/prajwal471/jocky/blob/master/jocky/runtime/builtins.py"
click node_harvesters "https://github.com/prajwal471/jocky/blob/master/jocky/runtime/harvesters.py"
click node_evidence "https://github.com/prajwal471/jocky/blob/master/jocky/runtime/evidence.py"
click node_crypto "https://github.com/prajwal471/jocky/blob/master/jocky/crypto/__init__.py"
click node_identity "https://github.com/prajwal471/jocky/blob/master/jocky/runtime/identity.py"
click node_dashboard "https://github.com/prajwal471/jocky/tree/master/jocky/server"
click node_harness "https://github.com/prajwal471/jocky/blob/master/jocky/eval/harness.py"
click node_baselines "https://github.com/prajwal471/jocky/blob/master/jocky/eval/baselines.py"
click node_measures "https://github.com/prajwal471/jocky/blob/master/jocky/eval/measures.py"
click node_proofs "https://github.com/prajwal471/jocky/blob/master/jocky/eval/equivalence.py"
click node_citations "https://github.com/prajwal471/jocky/blob/master/jocky/eval/citation.py"
click node_demo "https://github.com/prajwal471/jocky/blob/master/jocky/demo/bootstrap.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_parser,node_checker,node_types,node_jir toneBlue
class node_interpreter,node_builtins,node_harvesters,node_evidence,node_crypto,node_identity toneAmber
class node_api,node_auth,node_dispatch,node_store,node_dashboard toneMint
class node_coverage,node_metrics,node_harness,node_baselines,node_measures,node_proofs,node_citations toneRose
class node_demo,node_operator,node_host toneIndigo
```

## Components

### Mission language

- [Mission parser](https://github.com/prajwal471/jocky/blob/master/jocky/dsl/parser.py): `jocky/dsl/parser.py`
- [Safety checker](https://github.com/prajwal471/jocky/blob/master/jocky/dsl/checker.py): `jocky/dsl/checker.py`
- [Types and capabilities](https://github.com/prajwal471/jocky/blob/master/jocky/dsl/types.py): `jocky/dsl/types.py`
- [JIR representation](https://github.com/prajwal471/jocky/blob/master/jocky/dsl/jir.py): `jocky/dsl/jir.py`

### Collection and evidence

- [Mission interpreter](https://github.com/prajwal471/jocky/blob/master/jocky/runtime/interpreter.py): `jocky/runtime/interpreter.py`
- [Collector builtins](https://github.com/prajwal471/jocky/blob/master/jocky/runtime/builtins.py): `jocky/runtime/builtins.py`
- [Host harvesters](https://github.com/prajwal471/jocky/blob/master/jocky/runtime/harvesters.py): `jocky/runtime/harvesters.py`
- [Evidence chain](https://github.com/prajwal471/jocky/blob/master/jocky/runtime/evidence.py): `jocky/runtime/evidence.py`
- [Ed25519 signing](https://github.com/prajwal471/jocky/blob/master/jocky/crypto/__init__.py): `jocky/crypto/__init__.py`
- [Agent identity](https://github.com/prajwal471/jocky/blob/master/jocky/runtime/identity.py): `jocky/runtime/identity.py`

### Server and storage

- [HTTP API](https://github.com/prajwal471/jocky/blob/master/jocky/server/api.py): `jocky/server/api.py`
- [Token auth](https://github.com/prajwal471/jocky/blob/master/jocky/server/auth.py): `jocky/server/auth.py`
- [Mission dispatch](https://github.com/prajwal471/jocky/blob/master/jocky/server/dispatch.py): `jocky/server/dispatch.py`
- [Mission store](https://github.com/prajwal471/jocky/blob/master/jocky/server/db.py): `jocky/server/db.py`
- [Static dashboard](https://github.com/prajwal471/jocky/tree/master/jocky/server): `jocky/server`

### Review and evaluation

- [Coverage matrix](https://github.com/prajwal471/jocky/blob/master/jocky/server/coverage.py): `jocky/server/coverage.py`
- [Interop metrics](https://github.com/prajwal471/jocky/blob/master/jocky/server/metrics.py): `jocky/server/metrics.py`
- [Baseline harness](https://github.com/prajwal471/jocky/blob/master/jocky/eval/harness.py): `jocky/eval/harness.py`
- [Baseline cases](https://github.com/prajwal471/jocky/blob/master/jocky/eval/baselines.py): `jocky/eval/baselines.py`
- [Active measures](https://github.com/prajwal471/jocky/blob/master/jocky/eval/measures.py): `jocky/eval/measures.py`
- [Equivalence proofs](https://github.com/prajwal471/jocky/blob/master/jocky/eval/equivalence.py): `jocky/eval/equivalence.py`
- [Citation checks](https://github.com/prajwal471/jocky/blob/master/jocky/eval/citation.py): `jocky/eval/citation.py`

### Demo operations

- [Demo bootstrap](https://github.com/prajwal471/jocky/blob/master/jocky/demo/bootstrap.py): `jocky/demo/bootstrap.py`

### Other components

- **Investigator**
- **Forensic host**

## Connections

- Investigator → HTTP API: submits missions
- Investigator → Static dashboard: views results
- Static dashboard → HTTP API: calls routes
- HTTP API → Token auth: checks protected routes
- HTTP API → Mission dispatch: dispatches missions
- Mission dispatch → Mission parser: parses source
- Mission parser → Safety checker: checks structure
- Safety checker → Types and capabilities: validates capabilities
- Mission parser → JIR representation: serializes program
- Mission dispatch → Mission interpreter: runs mission
- Mission interpreter → Collector builtins: calls collectors
- Collector builtins → Host harvesters: reads host data
- Host harvesters → Forensic host: observes host
- Mission dispatch → Evidence chain: records observations
- Evidence chain → Ed25519 signing: signs records
- Evidence chain → Agent identity: uses agent identity
- Mission dispatch → Mission store: persists runs
- HTTP API → Mission store: reads mission data
- Mission dispatch → Coverage matrix: seeds coverage
- HTTP API → Interop metrics: serves interop metrics
- Baseline harness → Baseline cases: runs cases
- Baseline harness → Mission dispatch: executes missions
- Baseline harness → Equivalence proofs: checks invariants
- Baseline harness → Mission store: reads evaluation records
- Active measures → Mission dispatch: tests refusals
- Active measures → Mission store: checks persisted evidence
- Citation checks → Mission store: checks citations
- Demo bootstrap → Coverage matrix: seeds coverage
- Demo bootstrap → HTTP API: starts server