# lin891020/aoi-agent architecture

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

- Interactive diagram: https://gitdiagram.com/lin891020/aoi-agent
- Repository: https://github.com/lin891020/aoi-agent

## Overview

AOI-Agent reduces manual review of flagged circuit-board regions: a re-verifier settles clear cases, while an agent investigates uncertainty and sends unresolved cases to an operator. The same review station also lets supervisors ask production questions and inspect validated plans, charts, and answers. The graph preserves both workflows and the state and records they rely on. Relationships are limited to those documented in the README or visible in the supplied source index and excerpts; unsampled modules are represented only where their subsystem is clear.

Main entry points: [`src/aoi_agent/graph/flow.py`](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/graph/flow.py) (Review flow), [`src/aoi_agent/analysis/graph.py`](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/analysis/graph.py) (Question workflow), [`src/aoi_agent/station/service.py`](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/station/service.py) (Review service), [`src/aoi_agent/station/app.py`](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/station/app.py) (Station web app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inspection["Inspection and inference"]
  node_simulator["AOI simulator<br/>[simulator.py]"]
  node_inference["Re-verifier<br/>[inference.py]"]
end

subgraph group_review["Review workflow"]
  node_reviewflow["Review flow<br/>[flow.py]"]
  node_llm["Ollama client<br/>[ollama.py]"]
  node_classify["Classification tools<br/>[classify.py]"]
  node_standards["Standards retrieval<br/>[standards.py]"]
  node_rationale["Rationale checks<br/>[rationale_check.py]"]
end

subgraph group_records["Quality records"]
  node_provenance["Decision provenance<br/>[provenance.py]"]
  node_boardstore["Board records<br/>[boards.py]"]
  node_dispositions["Board disposition<br/>[dispositions.py]"]
  node_escalations["Escalation queue<br/>[escalations.py]"]
  node_database[("SQLite records<br/>[models.py]")]
end

subgraph group_station["Review station"]
  node_stationapp["Station web app<br/>[app.py]"]
  node_stationservice["Review service<br/>[service.py]"]
end

subgraph group_questions["Production questions"]
  node_analysisservice["Question service<br/>[service.py]"]
  node_analysisgraph["Question workflow<br/>[graph.py]"]
  node_plan["Plan validation<br/>[plan.py]"]
  node_prompts["Question prompts<br/>[prompts.py]"]
  node_claims["Answer validation<br/>[claims.py]"]
  node_production["Production queries<br/>[production.py]"]
  node_charts["Chart generation<br/>[charts.py]"]
end

node_operator(("Operator"))
node_supervisor(("Supervisor"))

node_operator -->|"submits board"| node_reviewflow
node_simulator -->|"flags candidates"| node_inference
node_reviewflow -->|"classifies with"| node_inference
node_reviewflow -->|"calls tools"| node_classify
node_reviewflow -->|"retrieves criteria"| node_standards
node_reviewflow -->|"requests rationale"| node_llm
node_reviewflow -->|"checks rationale"| node_rationale
node_reviewflow -->|"stamps decisions"| node_provenance
node_reviewflow -->|"escalates uncertainty"| node_operator
node_stationservice -->|"runs and resumes"| node_reviewflow
node_stationservice -->|"queues cases"| node_escalations
node_stationservice -->|"records decisions"| node_boardstore
node_stationservice -->|"records reviewer"| node_provenance
node_stationapp -->|"serves review"| node_stationservice
node_stationapp -->|"serves questions"| node_analysisservice
node_operator -->|"reviews queue"| node_stationapp
node_supervisor -->|"asks questions"| node_stationapp
node_analysisservice -->|"runs workflow"| node_analysisgraph
node_analysisgraph -->|"validates plans"| node_plan
node_analysisgraph -->|"builds prompts"| node_prompts
node_analysisgraph -->|"builds charts"| node_charts
node_analysisgraph -->|"checks answer"| node_claims
node_plan -->|"permits typed lookups"| node_production
node_analysisgraph -.->|"uses language model"| node_llm
node_boardstore -->|"reads records"| node_database
node_dispositions -->|"assesses boards"| node_database
node_escalations -->|"stores queue index"| node_database
node_production -->|"queries context"| node_database

click node_simulator "https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/aoi/simulator.py"
click node_inference "https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/vision/inference.py"
click node_reviewflow "https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/graph/flow.py"
click node_llm "https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/llm/ollama.py"
click node_classify "https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/mcp_servers/classify.py"
click node_standards "https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/mcp_servers/standards.py"
click node_rationale "https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/graph/rationale_check.py"
click node_provenance "https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/provenance.py"
click node_boardstore "https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/store/boards.py"
click node_dispositions "https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/store/dispositions.py"
click node_escalations "https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/store/escalations.py"
click node_database "https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/store/models.py"
click node_stationapp "https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/station/app.py"
click node_stationservice "https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/station/service.py"
click node_analysisservice "https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/analysis/service.py"
click node_analysisgraph "https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/analysis/graph.py"
click node_plan "https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/analysis/plan.py"
click node_prompts "https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/analysis/prompts.py"
click node_claims "https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/analysis/claims.py"
click node_production "https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/mcp_servers/production.py"
click node_charts "https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/analysis/charts.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_simulator,node_inference toneBlue
class node_reviewflow,node_llm,node_classify,node_standards,node_rationale toneAmber
class node_provenance,node_boardstore,node_dispositions,node_escalations,node_database toneMint
class node_stationapp,node_stationservice toneRose
class node_analysisservice,node_analysisgraph,node_plan,node_prompts,node_claims,node_production,node_charts,node_operator,node_supervisor toneIndigo
```

## Components

### Inspection and inference

- [AOI simulator](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/aoi/simulator.py): `src/aoi_agent/aoi/simulator.py`
- [Re-verifier](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/vision/inference.py): `src/aoi_agent/vision/inference.py`

### Review workflow

- [Review flow](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/graph/flow.py): `src/aoi_agent/graph/flow.py`
- [Ollama client](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/llm/ollama.py): `src/aoi_agent/llm/ollama.py`
- [Classification tools](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/mcp_servers/classify.py): `src/aoi_agent/mcp_servers/classify.py`
- [Standards retrieval](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/mcp_servers/standards.py): `src/aoi_agent/mcp_servers/standards.py`
- [Rationale checks](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/graph/rationale_check.py): `src/aoi_agent/graph/rationale_check.py`

### Quality records

- [Decision provenance](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/provenance.py): `src/aoi_agent/provenance.py`
- [Board records](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/store/boards.py): `src/aoi_agent/store/boards.py`
- [Board disposition](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/store/dispositions.py): `src/aoi_agent/store/dispositions.py`
- [Escalation queue](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/store/escalations.py): `src/aoi_agent/store/escalations.py`
- [SQLite records](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/store/models.py): `src/aoi_agent/store/models.py`

### Review station

- [Station web app](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/station/app.py): `src/aoi_agent/station/app.py`
- [Review service](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/station/service.py): `src/aoi_agent/station/service.py`

### Production questions

- [Question service](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/analysis/service.py): `src/aoi_agent/analysis/service.py`
- [Question workflow](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/analysis/graph.py): `src/aoi_agent/analysis/graph.py`
- [Plan validation](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/analysis/plan.py): `src/aoi_agent/analysis/plan.py`
- [Question prompts](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/analysis/prompts.py): `src/aoi_agent/analysis/prompts.py`
- [Answer validation](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/analysis/claims.py): `src/aoi_agent/analysis/claims.py`
- [Production queries](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/mcp_servers/production.py): `src/aoi_agent/mcp_servers/production.py`
- [Chart generation](https://github.com/lin891020/aoi-agent/blob/master/src/aoi_agent/analysis/charts.py): `src/aoi_agent/analysis/charts.py`

### Other components

- **Operator**
- **Supervisor**

## Connections

- Operator → Review flow: submits board (evidence: `README.md`)
- AOI simulator → Re-verifier: flags candidates (evidence: `src/aoi_agent/vision/inference.py`)
- Review flow → Re-verifier: classifies with (evidence: `src/aoi_agent/graph/flow.py`)
- Review flow → Classification tools: calls tools (evidence: `src/aoi_agent/graph/flow.py`)
- Review flow → Standards retrieval: retrieves criteria (evidence: `src/aoi_agent/graph/flow.py`)
- Review flow → Ollama client: requests rationale (evidence: `src/aoi_agent/graph/flow.py`)
- Review flow → Rationale checks: checks rationale (evidence: `src/aoi_agent/graph/flow.py`)
- Review flow → Decision provenance: stamps decisions (evidence: `src/aoi_agent/graph/flow.py`)
- Review flow → Operator: escalates uncertainty (evidence: `README.md`)
- Review service → Review flow: runs and resumes (evidence: `src/aoi_agent/station/service.py`)
- Review service → Escalation queue: queues cases (evidence: `src/aoi_agent/station/service.py`)
- Review service → Board records: records decisions (evidence: `src/aoi_agent/station/service.py`)
- Review service → Decision provenance: records reviewer (evidence: `src/aoi_agent/station/service.py`)
- Station web app → Review service: serves review (evidence: `src/aoi_agent/station/app.py`)
- Station web app → Question service: serves questions (evidence: `src/aoi_agent/station/app.py`)
- Operator → Station web app: reviews queue (evidence: `README.md`)
- Supervisor → Station web app: asks questions (evidence: `README.md`)
- Question service → Question workflow: runs workflow (evidence: `src/aoi_agent/analysis/service.py`)
- Question workflow → Plan validation: validates plans (evidence: `src/aoi_agent/analysis/graph.py`)
- Question workflow → Question prompts: builds prompts (evidence: `src/aoi_agent/analysis/graph.py`)
- Question workflow → Chart generation: builds charts (evidence: `src/aoi_agent/analysis/graph.py`)
- Question workflow → Answer validation: checks answer (evidence: `src/aoi_agent/analysis/claims.py`)
- Plan validation → Production queries: permits typed lookups (evidence: `README.md`)
- Question workflow → Ollama client: uses language model
- Board records → SQLite records: reads records (evidence: `src/aoi_agent/store/boards.py`)
- Board disposition → SQLite records: assesses boards (evidence: `src/aoi_agent/store/dispositions.py`)
- Escalation queue → SQLite records: stores queue index (evidence: `src/aoi_agent/store/models.py`)
- Production queries → SQLite records: queries context (evidence: `src/aoi_agent/mcp_servers/production.py`)
