How isb333/system-card-scanner works
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: pipeline.py Scan Pipeline · scout.py Scout · parsers Static Parsers · agents Analysis Agents
Components 21
Scan Planning
- CLI
main.py - Scan Pipeline
orchestrator/pipeline.py - Scout
orchestrator/scout.py - Scan Plan
orchestrator/scan_plan.py - File Router
orchestrator/shepherd.py
Project Analysis
- Static Parsers
parsers - Manifest Parser
parsers/manifest_parser.py - Route Parser
parsers/route_parser.py - Git Signals
parsers/git_parser.py - Analysis Agents
agents - LLM Client
llm_client.py
Grounding
- Citation Validator
orchestrator/validator.py - Citation Resolver
orchestrator/citation_resolver.py
Card Output
- Card Synthesizer
synthesizer/synthesizer.py - Fact Renderer
synthesizer/fact_renderer.py - Card Writer
synthesizer/card_writer.py - Safe Promotion
synthesizer/promotion.py
Other components
- Developer
- Target Codebase
- LLM Provider
- System Card
Connections 28
- 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