# isb333/system-card-scanner architecture

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

- Interactive diagram: https://gitdiagram.com/isb333/system-card-scanner
- Repository: https://github.com/isb333/system-card-scanner

## Overview

system-card-generator scans a developer-selected codebase and produces a grounded Markdown System Card. The principal workflow is CLI invocation → static inventory and planning → file routing and specialist analysis → citation validation with correction → synthesis and safe output promotion. The README also documents deeper architecture, API, data-model, dependency, data-flow, and failure-mode analyses, plus incremental rescanning. Source excerpts are partial, so links among unsampled internals are shown only where README documentation supports them.

Main entry points: [`orchestrator/pipeline.py`](https://github.com/isb333/system-card-scanner/blob/main/orchestrator/pipeline.py) (Scan Pipeline), [`orchestrator/scout.py`](https://github.com/isb333/system-card-scanner/blob/main/orchestrator/scout.py) (Scout), [`parsers`](https://github.com/isb333/system-card-scanner/tree/main/parsers) (Static Parsers), [`agents`](https://github.com/isb333/system-card-scanner/tree/main/agents) (Analysis Agents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scan["Scan Planning"]
  node_cli["CLI<br/>[main.py]"]
  node_pipeline["Scan Pipeline<br/>[pipeline.py]"]
  node_scout["Scout<br/>[scout.py]"]
  node_plan["Scan Plan<br/>[scan_plan.py]"]
  node_shepherd["File Router<br/>[shepherd.py]"]
end

subgraph group_analysis["Project Analysis"]
  node_static_parsers["Static Parsers"]
  node_manifest["Manifest Parser<br/>[manifest_parser.py]"]
  node_route["Route Parser<br/>[route_parser.py]"]
  node_git["Git Signals<br/>[git_parser.py]"]
  node_workers["Analysis Agents"]
  node_llm_client["LLM Client<br/>[llm_client.py]"]
end

subgraph group_grounding["Grounding"]
  node_validator["Citation Validator<br/>[validator.py]"]
  node_citation["Citation Resolver"]
end

subgraph group_output["Card Output"]
  node_synth["Card Synthesizer<br/>[synthesizer.py]"]
  node_renderer["Fact Renderer<br/>[fact_renderer.py]"]
  node_writer["Card Writer<br/>[card_writer.py]"]
  node_promotion["Safe Promotion<br/>[promotion.py]"]
end

node_developer(("Developer"))
node_target["Target Codebase"]
node_model_service{{"LLM Provider"}}
node_card["System Card"]

node_developer -->|"invokes"| node_cli
node_cli -->|"starts scan"| node_pipeline
node_pipeline -->|"requests plan"| node_scout
node_scout -->|"inspects files"| node_target
node_scout -->|"runs static analysis"| node_static_parsers
node_static_parsers -->|"parses manifests"| node_manifest
node_static_parsers -->|"extracts routes"| node_route
node_static_parsers -->|"collects signals"| node_git
node_scout -->|"produces"| node_plan
node_pipeline -->|"routes files"| node_shepherd
node_plan -->|"provides assignments"| node_shepherd
node_shepherd -->|"dispatches files"| node_workers
node_pipeline -->|"runs agents"| node_workers
node_workers -->|"reads assigned files"| node_target
node_workers -->|"requests analysis"| node_llm_client
node_llm_client -->|"sends prompts"| node_model_service
node_model_service -->|"returns responses"| node_llm_client
node_pipeline -->|"validates reports"| node_validator
node_validator -->|"resolves citations"| node_citation
node_citation -->|"checks source spans"| node_target
node_validator -.->|"requests correction routing"| node_shepherd
node_pipeline -->|"synthesizes grounded reports"| node_synth
node_synth -->|"requests card prose"| node_llm_client
node_synth -->|"renders structured facts"| node_renderer
node_pipeline -->|"writes card"| node_writer
node_writer -->|"stages output"| node_promotion
node_promotion -->|"promotes validated output"| node_card
node_card -->|"writes into project"| node_target

click node_cli "https://github.com/isb333/system-card-scanner/blob/main/main.py"
click node_pipeline "https://github.com/isb333/system-card-scanner/blob/main/orchestrator/pipeline.py"
click node_scout "https://github.com/isb333/system-card-scanner/blob/main/orchestrator/scout.py"
click node_plan "https://github.com/isb333/system-card-scanner/blob/main/orchestrator/scan_plan.py"
click node_shepherd "https://github.com/isb333/system-card-scanner/blob/main/orchestrator/shepherd.py"
click node_static_parsers "https://github.com/isb333/system-card-scanner/tree/main/parsers"
click node_manifest "https://github.com/isb333/system-card-scanner/blob/main/parsers/manifest_parser.py"
click node_route "https://github.com/isb333/system-card-scanner/blob/main/parsers/route_parser.py"
click node_git "https://github.com/isb333/system-card-scanner/blob/main/parsers/git_parser.py"
click node_workers "https://github.com/isb333/system-card-scanner/tree/main/agents"
click node_llm_client "https://github.com/isb333/system-card-scanner/blob/main/llm_client.py"
click node_validator "https://github.com/isb333/system-card-scanner/blob/main/orchestrator/validator.py"
click node_citation "https://github.com/isb333/system-card-scanner/blob/main/orchestrator/citation_resolver.py"
click node_synth "https://github.com/isb333/system-card-scanner/blob/main/synthesizer/synthesizer.py"
click node_renderer "https://github.com/isb333/system-card-scanner/blob/main/synthesizer/fact_renderer.py"
click node_writer "https://github.com/isb333/system-card-scanner/blob/main/synthesizer/card_writer.py"
click node_promotion "https://github.com/isb333/system-card-scanner/blob/main/synthesizer/promotion.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_pipeline,node_scout,node_plan,node_shepherd toneBlue
class node_static_parsers,node_manifest,node_route,node_git,node_workers,node_llm_client toneAmber
class node_validator,node_citation toneMint
class node_synth,node_renderer,node_writer,node_promotion toneRose
class node_developer,node_target,node_model_service,node_card toneIndigo
```

## Components

### Scan Planning

- [CLI](https://github.com/isb333/system-card-scanner/blob/main/main.py): `main.py`
- [Scan Pipeline](https://github.com/isb333/system-card-scanner/blob/main/orchestrator/pipeline.py): `orchestrator/pipeline.py`
- [Scout](https://github.com/isb333/system-card-scanner/blob/main/orchestrator/scout.py): `orchestrator/scout.py`
- [Scan Plan](https://github.com/isb333/system-card-scanner/blob/main/orchestrator/scan_plan.py): `orchestrator/scan_plan.py`
- [File Router](https://github.com/isb333/system-card-scanner/blob/main/orchestrator/shepherd.py): `orchestrator/shepherd.py`

### Project Analysis

- [Static Parsers](https://github.com/isb333/system-card-scanner/tree/main/parsers): `parsers`
- [Manifest Parser](https://github.com/isb333/system-card-scanner/blob/main/parsers/manifest_parser.py): `parsers/manifest_parser.py`
- [Route Parser](https://github.com/isb333/system-card-scanner/blob/main/parsers/route_parser.py): `parsers/route_parser.py`
- [Git Signals](https://github.com/isb333/system-card-scanner/blob/main/parsers/git_parser.py): `parsers/git_parser.py`
- [Analysis Agents](https://github.com/isb333/system-card-scanner/tree/main/agents): `agents`
- [LLM Client](https://github.com/isb333/system-card-scanner/blob/main/llm_client.py): `llm_client.py`

### Grounding

- [Citation Validator](https://github.com/isb333/system-card-scanner/blob/main/orchestrator/validator.py): `orchestrator/validator.py`
- [Citation Resolver](https://github.com/isb333/system-card-scanner/blob/main/orchestrator/citation_resolver.py): `orchestrator/citation_resolver.py`

### Card Output

- [Card Synthesizer](https://github.com/isb333/system-card-scanner/blob/main/synthesizer/synthesizer.py): `synthesizer/synthesizer.py`
- [Fact Renderer](https://github.com/isb333/system-card-scanner/blob/main/synthesizer/fact_renderer.py): `synthesizer/fact_renderer.py`
- [Card Writer](https://github.com/isb333/system-card-scanner/blob/main/synthesizer/card_writer.py): `synthesizer/card_writer.py`
- [Safe Promotion](https://github.com/isb333/system-card-scanner/blob/main/synthesizer/promotion.py): `synthesizer/promotion.py`

### Other components

- **Developer**
- **Target Codebase**
- **LLM Provider**
- **System Card**

## Connections

- Developer → CLI: invokes
- CLI → Scan Pipeline: starts scan
- Scan Pipeline → Scout: requests plan
- Scout → Target Codebase: inspects files
- Scout → Static Parsers: runs static analysis
- Static Parsers → Manifest Parser: parses manifests
- Static Parsers → Route Parser: extracts routes
- Static Parsers → Git Signals: collects signals
- Scout → Scan Plan: produces
- Scan Pipeline → File Router: routes files
- Scan Plan → File Router: provides assignments
- File Router → Analysis Agents: dispatches files
- Scan Pipeline → Analysis Agents: runs agents
- Analysis Agents → Target Codebase: reads assigned files
- Analysis Agents → LLM Client: requests analysis
- LLM Client → LLM Provider: sends prompts
- LLM Provider → LLM Client: returns responses
- Scan Pipeline → Citation Validator: validates reports
- Citation Validator → Citation Resolver: resolves citations
- Citation Resolver → Target Codebase: checks source spans
- Citation Validator → File Router: requests correction routing
- Scan Pipeline → Card Synthesizer: synthesizes grounded reports
- Card Synthesizer → LLM Client: requests card prose
- Card Synthesizer → Fact Renderer: renders structured facts
- Scan Pipeline → Card Writer: writes card
- Card Writer → Safe Promotion: stages output
- Safe Promotion → System Card: promotes validated output
- System Card → Target Codebase: writes into project