# lyslama/k5-day8-vincon-fromworkflowstoagents architecture

> Architecture diagram of the GitHub repository lyslama/k5-day8-vincon-fromworkflowstoagents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lyslama/k5-day8-vincon-fromworkflowstoagents
- Repository: https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents

## Overview

LogiX-VN is a teaching harness for processing simulated shipping-refund claims through four competing architectures, returning a common run result and comparing measured outcomes. The workflow is: a user runs a shape for a claim; it reads scoped claim/order and policy data, computes a quote, and asks the host to authorize and commit any refund; the run emits a trace and result for evaluation. README documentation establishes the intended roles of the unsampled orchestrator and benchmark subsystems; their internal calls are not inferred here.

Main entry points: [`src/lab8/app.py`](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/app.py) (Shape runner), [`src/lab8/shapes/workflow.py`](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/shapes/workflow.py) (Fixed workflow), [`src/lab8/shapes/single.py`](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/shapes/single.py) (Single agent), [`src/lab8/shapes/swarm_reference.py`](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/shapes/swarm_reference.py) (Reference swarm)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Execution and shapes"]
  node_cli["Run CLI<br/>[run.py]"]
  node_runner["Shape runner<br/>[app.py]"]
  node_workflow["Fixed workflow<br/>[workflow.py]"]
  node_single["Single agent<br/>[single.py]"]
  node_orchestrator["Orchestrator shape<br/>[orchestrator.py]"]
  node_swarm["Reference swarm<br/>[swarm_reference.py]"]
  node_react["ReAct runtime<br/>[runtime.py]"]
  node_handoff["Safe handoff<br/>[handoff.py]"]
  node_mockllm["Seeded MockLLM<br/>[mock_llm.py]"]
end

subgraph group_domain["Claim and policy domain"]
  node_tools["Read tools<br/>[tools.py]"]
  node_quote["Compensation quote<br/>[compensation.py]"]
  node_config["Pinned configuration<br/>[config_loader.py]"]
  node_world["Public claim data"]
  node_claims["Public claims"]
end

subgraph group_host["Host safety and state"]
  node_host["Refund host<br/>[durability.py]"]
  node_policy["Authorization policy<br/>[policy.py]"]
  node_store[("SQLite world and ledger<br/>[db.py]")]
  node_contract["Run result contract<br/>[schemas.py]"]
end

subgraph group_evaluation["Trace and evaluation"]
  node_trace["Run trace<br/>[trace.py]"]
  node_metrics["Benchmark metrics<br/>[metrics.py]"]
  node_benchmark["Shape benchmark<br/>[benchmark.py]"]
end

node_user(("Lab user"))

node_user -->|"runs claims"| node_cli
node_cli -->|"invokes runner"| node_runner
node_runner -->|"prepares store"| node_store
node_runner -->|"dispatches shape"| node_workflow
node_runner -->|"dispatches shape"| node_single
node_runner -->|"dispatches shape"| node_orchestrator
node_runner -->|"dispatches shape"| node_swarm
node_runner -->|"loads claims"| node_claims
node_runner -->|"loads world"| node_world
node_workflow -->|"reads and quotes"| node_tools
node_workflow -->|"requests refund"| node_host
node_single -->|"runs ReAct"| node_react
node_single -->|"requests refund"| node_host
node_swarm -->|"creates handoff"| node_handoff
node_swarm -->|"requests refund"| node_host
node_react -->|"dispatches tools"| node_tools
node_react -->|"uses handoff"| node_handoff
node_tools -->|"calculates quote"| node_quote
node_tools -->|"reads policy date"| node_config
node_mockllm -->|"reads pricing"| node_config
node_host -->|"checks authorization"| node_policy
node_host -->|"commits ledger"| node_store
node_workflow -->|"records run"| node_trace
node_single -->|"records run"| node_trace
node_swarm -->|"records run"| node_trace
node_benchmark -.->|"summarizes trials"| node_metrics
node_metrics -->|"checks ledger"| node_store
node_mockllm -->|"provides completions"| node_single
node_mockllm -->|"provides completions"| node_swarm
node_workflow -->|"returns result"| node_contract

click node_cli "https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/run.py"
click node_runner "https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/app.py"
click node_workflow "https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/shapes/workflow.py"
click node_single "https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/shapes/single.py"
click node_orchestrator "https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/shapes/orchestrator.py"
click node_swarm "https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/shapes/swarm_reference.py"
click node_react "https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/runtime.py"
click node_handoff "https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/handoff.py"
click node_mockllm "https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/mock_llm.py"
click node_tools "https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/tools.py"
click node_quote "https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/compensation.py"
click node_config "https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/config_loader.py"
click node_world "https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/data/public_world_state.json"
click node_claims "https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/data/public_claims.jsonl"
click node_host "https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/durability.py"
click node_policy "https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/policy.py"
click node_store "https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/db.py"
click node_contract "https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/schemas.py"
click node_trace "https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/trace.py"
click node_metrics "https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/metrics.py"
click node_benchmark "https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/benchmark.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_runner,node_workflow,node_single,node_orchestrator,node_swarm,node_react,node_handoff,node_mockllm,node_user toneBlue
class node_tools,node_quote,node_config,node_world,node_claims toneAmber
class node_host,node_policy,node_store,node_contract toneMint
class node_trace,node_metrics,node_benchmark toneRose
```

## Components

### Execution and shapes

- [Run CLI](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/run.py): `src/lab8/run.py`
- [Shape runner](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/app.py): `src/lab8/app.py`
- [Fixed workflow](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/shapes/workflow.py): `src/lab8/shapes/workflow.py`
- [Single agent](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/shapes/single.py): `src/lab8/shapes/single.py`
- [Orchestrator shape](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/shapes/orchestrator.py): `src/lab8/shapes/orchestrator.py`
- [Reference swarm](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/shapes/swarm_reference.py): `src/lab8/shapes/swarm_reference.py`
- [ReAct runtime](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/runtime.py): `src/lab8/runtime.py`
- [Safe handoff](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/handoff.py): `src/lab8/handoff.py`
- [Seeded MockLLM](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/mock_llm.py): `src/lab8/mock_llm.py`

### Claim and policy domain

- [Read tools](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/tools.py): `src/lab8/tools.py`
- [Compensation quote](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/compensation.py): `src/lab8/compensation.py`
- [Pinned configuration](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/config_loader.py): `src/lab8/config_loader.py`
- [Public claim data](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/data/public_world_state.json): `src/data/public_world_state.json`
- [Public claims](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/data/public_claims.jsonl): `src/data/public_claims.jsonl`

### Host safety and state

- [Refund host](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/durability.py): `src/lab8/durability.py`
- [Authorization policy](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/policy.py): `src/lab8/policy.py`
- [SQLite world and ledger](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/db.py): `src/lab8/db.py`
- [Run result contract](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/schemas.py): `src/lab8/schemas.py`

### Trace and evaluation

- [Run trace](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/trace.py): `src/lab8/trace.py`
- [Benchmark metrics](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/metrics.py): `src/lab8/metrics.py`
- [Shape benchmark](https://github.com/lyslama/k5-day8-vincon-fromworkflowstoagents/blob/main/src/lab8/benchmark.py): `src/lab8/benchmark.py`

### Other components

- **Lab user**

## Connections

- Lab user → Run CLI: runs claims (evidence: `src/lab8/run.py`)
- Run CLI → Shape runner: invokes runner (evidence: `src/lab8/run.py`)
- Shape runner → SQLite world and ledger: prepares store (evidence: `src/lab8/app.py`)
- Shape runner → Fixed workflow: dispatches shape (evidence: `src/lab8/app.py`)
- Shape runner → Single agent: dispatches shape (evidence: `src/lab8/app.py`)
- Shape runner → Orchestrator shape: dispatches shape (evidence: `src/lab8/app.py`)
- Shape runner → Reference swarm: dispatches shape (evidence: `src/lab8/app.py`)
- Shape runner → Public claims: loads claims (evidence: `src/lab8/app.py`)
- Shape runner → Public claim data: loads world (evidence: `src/lab8/app.py`)
- Fixed workflow → Read tools: reads and quotes (evidence: `src/lab8/shapes/workflow.py`)
- Fixed workflow → Refund host: requests refund (evidence: `src/lab8/shapes/workflow.py`)
- Single agent → ReAct runtime: runs ReAct (evidence: `src/lab8/shapes/single.py`)
- Single agent → Refund host: requests refund (evidence: `src/lab8/shapes/single.py`)
- Reference swarm → Safe handoff: creates handoff (evidence: `src/lab8/shapes/swarm_reference.py`)
- Reference swarm → Refund host: requests refund (evidence: `src/lab8/shapes/swarm_reference.py`)
- ReAct runtime → Read tools: dispatches tools (evidence: `src/lab8/runtime.py`)
- ReAct runtime → Safe handoff: uses handoff (evidence: `src/lab8/runtime.py`)
- Read tools → Compensation quote: calculates quote (evidence: `src/lab8/tools.py`)
- Read tools → Pinned configuration: reads policy date (evidence: `src/lab8/tools.py`)
- Seeded MockLLM → Pinned configuration: reads pricing (evidence: `src/lab8/mock_llm.py`)
- Refund host → Authorization policy: checks authorization (evidence: `src/lab8/durability.py`)
- Refund host → SQLite world and ledger: commits ledger (evidence: `src/lab8/durability.py`)
- Fixed workflow → Run trace: records run (evidence: `src/lab8/shapes/workflow.py`)
- Single agent → Run trace: records run (evidence: `src/lab8/shapes/single.py`)
- Reference swarm → Run trace: records run (evidence: `src/lab8/shapes/swarm_reference.py`)
- Shape benchmark → Benchmark metrics: summarizes trials
- Benchmark metrics → SQLite world and ledger: checks ledger (evidence: `src/lab8/metrics.py`)
- Seeded MockLLM → Single agent: provides completions (evidence: `src/lab8/shapes/single.py`)
- Seeded MockLLM → Reference swarm: provides completions (evidence: `src/lab8/shapes/swarm_reference.py`)
- Fixed workflow → Run result contract: returns result (evidence: `src/lab8/shapes/workflow.py`)
