# afnan-0206/isocheck architecture

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

- Interactive diagram: https://gitdiagram.com/afnan-0206/isocheck
- Repository: https://github.com/afnan-0206/isocheck

## Overview

IsoCheck checks client-observed transaction histories for isolation anomalies. In the principal workflow, concurrent workload clients generate list-append transactions against PostgreSQL; the runner records invoke/completion events as JSONL, and the CLI parses a history and asks the checker to infer version orders, construct dependency graphs, and report anomaly witnesses. The harness also supports seeded acceptance campaigns and a buggy-database control. Core analysis and harness links are grounded in excerpts or README statements; unsampled campaign internals are not expanded beyond documented links.

Main entry points: [`core/src/checker.cpp`](https://github.com/afnan-0206/isocheck/blob/main/core/src/checker.cpp) (Anomaly Checker), [`harness/runner.py`](https://github.com/afnan-0206/isocheck/blob/main/harness/runner.py) (History Runner), [`cli/main.cpp`](https://github.com/afnan-0206/isocheck/blob/main/cli/main.cpp) (Checker CLI), [`harness/run_campaign.py`](https://github.com/afnan-0206/isocheck/blob/main/harness/run_campaign.py) (Acceptance Campaign)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_harness["Workload Harness"]
  node_generator["Workload Generator<br/>[workload.py]"]
  node_runner["History Runner<br/>[runner.py]"]
  node_postgres_client["PostgreSQL Harness<br/>[postgres.py]"]
  node_campaign["Acceptance Campaign<br/>[run_campaign.py]"]
  node_buggy_runner["Buggy Control Runner<br/>[buggy_runner.py]"]
end

subgraph group_analysis["History Analysis"]
  node_history["History Parsing<br/>[history.cpp]"]
  node_checker["Anomaly Checker<br/>[checker.cpp]"]
  node_version_order["Version Inference<br/>[version_order.cpp]"]
end

subgraph group_graph["Dependency Analysis"]
  node_dependency_graph["Graph Construction<br/>[checker.cpp]"]
  node_cycle_search["Cycle Search<br/>[graph.cpp]"]
end

subgraph group_results["Results"]
  node_cli["Checker CLI<br/>[main.cpp]"]
  node_report["Verdict Output<br/>[main.cpp]"]
end

node_operator(("Operator"))
node_postgres[("PostgreSQL")]

node_operator -->|"starts campaign"| node_campaign
node_operator -->|"runs workload"| node_runner
node_generator -->|"supplies templates"| node_runner
node_runner -->|"executes transactions"| node_postgres_client
node_postgres_client -->|"runs SQL"| node_postgres
node_runner -->|"invokes checker"| node_cli
node_campaign -->|"checks histories"| node_cli
node_campaign -.->|"runs workload"| node_runner
node_buggy_runner -->|"runs checker"| node_cli
node_cli -->|"parses history"| node_history
node_cli -->|"checks history"| node_checker
node_checker -->|"extracts transactions"| node_history
node_checker -->|"infers versions"| node_version_order
node_checker -->|"builds graph"| node_dependency_graph
node_checker -->|"finds cycles"| node_cycle_search
node_dependency_graph -->|"uses version orders"| node_version_order
node_cycle_search -->|"searches graph"| node_dependency_graph
node_checker -->|"returns verdict"| node_report
node_report -->|"shows result"| node_operator

click node_generator "https://github.com/afnan-0206/isocheck/blob/main/harness/workload.py"
click node_runner "https://github.com/afnan-0206/isocheck/blob/main/harness/runner.py"
click node_postgres_client "https://github.com/afnan-0206/isocheck/blob/main/harness/postgres.py"
click node_campaign "https://github.com/afnan-0206/isocheck/blob/main/harness/run_campaign.py"
click node_buggy_runner "https://github.com/afnan-0206/isocheck/blob/main/harness/buggy_runner.py"
click node_cli "https://github.com/afnan-0206/isocheck/blob/main/cli/main.cpp"
click node_history "https://github.com/afnan-0206/isocheck/blob/main/core/src/history.cpp"
click node_checker "https://github.com/afnan-0206/isocheck/blob/main/core/src/checker.cpp"
click node_version_order "https://github.com/afnan-0206/isocheck/blob/main/core/src/version_order.cpp"
click node_dependency_graph "https://github.com/afnan-0206/isocheck/blob/main/core/src/checker.cpp"
click node_cycle_search "https://github.com/afnan-0206/isocheck/blob/main/core/src/graph.cpp"
click node_report "https://github.com/afnan-0206/isocheck/blob/main/cli/main.cpp"

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_generator,node_runner,node_postgres_client,node_campaign,node_buggy_runner toneBlue
class node_history,node_checker,node_version_order,node_postgres toneAmber
class node_dependency_graph,node_cycle_search toneMint
class node_cli,node_report toneRose
class node_operator toneIndigo
```

## Components

### Workload Harness

- [Workload Generator](https://github.com/afnan-0206/isocheck/blob/main/harness/workload.py): `harness/workload.py`
- [History Runner](https://github.com/afnan-0206/isocheck/blob/main/harness/runner.py): `harness/runner.py`
- [PostgreSQL Harness](https://github.com/afnan-0206/isocheck/blob/main/harness/postgres.py): `harness/postgres.py`
- [Acceptance Campaign](https://github.com/afnan-0206/isocheck/blob/main/harness/run_campaign.py): `harness/run_campaign.py`
- [Buggy Control Runner](https://github.com/afnan-0206/isocheck/blob/main/harness/buggy_runner.py): `harness/buggy_runner.py`

### History Analysis

- [History Parsing](https://github.com/afnan-0206/isocheck/blob/main/core/src/history.cpp): `core/src/history.cpp`
- [Anomaly Checker](https://github.com/afnan-0206/isocheck/blob/main/core/src/checker.cpp): `core/src/checker.cpp`
- [Version Inference](https://github.com/afnan-0206/isocheck/blob/main/core/src/version_order.cpp): `core/src/version_order.cpp`

### Dependency Analysis

- [Graph Construction](https://github.com/afnan-0206/isocheck/blob/main/core/src/checker.cpp): `core/src/checker.cpp`
- [Cycle Search](https://github.com/afnan-0206/isocheck/blob/main/core/src/graph.cpp): `core/src/graph.cpp`

### Results

- [Checker CLI](https://github.com/afnan-0206/isocheck/blob/main/cli/main.cpp): `cli/main.cpp`
- [Verdict Output](https://github.com/afnan-0206/isocheck/blob/main/cli/main.cpp): `cli/main.cpp`

### Other components

- **Operator**
- **PostgreSQL**

## Connections

- Operator → Acceptance Campaign: starts campaign (evidence: `README.md`)
- Operator → History Runner: runs workload (evidence: `README.md`)
- Workload Generator → History Runner: supplies templates (evidence: `harness/runner.py`)
- History Runner → PostgreSQL Harness: executes transactions (evidence: `harness/runner.py`)
- PostgreSQL Harness → PostgreSQL: runs SQL (evidence: `harness/postgres.py`)
- History Runner → Checker CLI: invokes checker (evidence: `harness/runner.py`)
- Acceptance Campaign → Checker CLI: checks histories (evidence: `harness/run_campaign.py`)
- Acceptance Campaign → History Runner: runs workload (evidence: `harness/run_campaign.py`)
- Buggy Control Runner → Checker CLI: runs checker (evidence: `README.md`)
- Checker CLI → History Parsing: parses history (evidence: `cli/main.cpp`)
- Checker CLI → Anomaly Checker: checks history (evidence: `cli/main.cpp`)
- Anomaly Checker → History Parsing: extracts transactions
- Anomaly Checker → Version Inference: infers versions
- Anomaly Checker → Graph Construction: builds graph (evidence: `core/src/checker.cpp`)
- Anomaly Checker → Cycle Search: finds cycles
- Graph Construction → Version Inference: uses version orders
- Cycle Search → Graph Construction: searches graph
- Anomaly Checker → Verdict Output: returns verdict
- Verdict Output → Operator: shows result (evidence: `cli/main.cpp`)
