How sysuselab/repodoc works
RepoDoc is a Python CLI application for building and maintaining documentation from a repository-level knowledge graph. The system is centered around analyzing source code, turning that analysis into a graph, optionally clustering related modules, and then using an LLM to generate or update docs.
1. Entry point and command surface
- The top-level interface is the repodoc CLI, with commands for analyze, cluster, docs, generate, and update.
- This suggests a staged workflow: inspect the repository first, derive structure, then produce documentation, with a separate path for incremental maintenance.
2. Core pipeline boundary
- repodoc/pipeline/generator.py is the orchestration layer that likely ties analysis, graph construction, clustering, and doc generation together.
- The pipeline is the main integration boundary between static code understanding and LLM-driven output.
3. Repository analysis subsystem
- repodoc/src/analysis/ is the main static-analysis layer.
- It includes repo-level analysis, AST parsing, call-graph building, dependency-graph building, topological sorting, and diff analysis for updates.
- This subsystem is responsible for extracting structural knowledge from source code before anything is written to the graph or passed to the LLM.
4. Language-specific analyzers
- repodoc/src/analysis/analyzers/ contains per-language analyzers for C, C++, C#, Go, Java, JavaScript, PHP, Python, Rust, and TypeScript.
- This indicates the system is multi-language and uses language-aware parsing rather than a single generic parser.
- The analyzer layer is where repository content is normalized into a common intermediate model.
5. Graph model and builder
- repodoc/src/graph/ contains the graph data model and the graph builder.
- The graph is the central repository knowledge representation, likely storing entities such as modules, files, symbols, dependencies, and relationships derived from analysis.
- This graph is the key handoff point for downstream tooling, especially documentation and query features.
6. Clustering subsystem
- repodoc/src/clustering/cluster_modules.py and related prompts indicate a module-clustering stage.
- Clustering appears to group related code into higher-level units, which is useful for summarizing large repos and generating coherent docs.
- This is an abstraction layer over the raw graph, helping convert fine-grained code structure into documentation-friendly groupings.
7. Incremental update path
- repodoc/src/incremental/ contains a code extractor and incremental updater.
- This implies support for change-aware regeneration rather than full recomputation every time.
- The diff-analysis component in the analysis layer likely feeds this update path so only affected portions of the graph/docs are refreshed.
8. LLM integration
- repodoc/src/llm.py plus src/tools/llm_tool.py and skill prompt files show that documentation generation is LLM-backed.
- Configuration via LLM_BASE_URL, LLM_API_KEY, and MAIN_MODEL means the model endpoint is external and pluggable.
- The architecture separates model access from the domain logic, allowing different providers or hosted endpoints.
9. Skills and prompt-driven behavior
- repodoc/src/skills/ defines higher-level LLM tasks such as code analysis, doc writing, and graph querying.
- Each skill has instructions and YAML metadata, indicating a prompt-centric design where behavior is packaged as reusable capabilities.
- This layer sits between raw tools and the pipeline, shaping how the LLM is instructed for each task.
10. Tooling abstraction
- repodoc/src/tools/ provides file, graph, and LLM tools behind common base interfaces.
- This is an important architectural boundary: skills and agents should use tools rather than touching filesystem/graph/LLM concerns directly.
- It keeps side effects and external interactions isolated.
11. Agent/factory layer
- repodoc/src/agents/ contains base and factory code, suggesting the system can instantiate different agent roles for specific tasks.
- Even if lightweight, this provides a coordination layer above tools and skills, likely used to compose workflows for analysis, doc writing, or querying.
12. Security and pattern utilities
- repodoc/src/analysis/utils/security.py and patterns.py indicate support code for safe handling and code-pattern recognition.
- These utilities likely help filter, classify, or safely inspect repository content before it is passed into downstream generation steps.
13. Runtime and packaging
- The project is a Python package managed with pyproject.toml and uv.lock, targeting a modern Python toolchain.
- .env.example shows the runtime depends on external LLM configuration rather than bundling a model locally.
14. Overall data flow
- The main path is: repository path in the CLI → analysis/parsing → graph construction → optional clustering and query preparation → LLM-assisted documentation generation → output docs.
- The update path reuses the same graph/analysis foundation but starts from diffs or extracted changes to refresh documentation incrementally.
Main entry points: generator.py Pipeline · repo_analyzer.py Repo analysis · analysis_service.py Analysis svc · builder.py Graph builder
Components 22
CLI
Command surface and pipeline entry points.
Analysis
Static repository understanding and derived structure.
- Repo analysis · Runs repository-wide analysis and dispatches language-specific parsing.
repodoc/src/analysis/repo_analyzer.py - Analysis svc · Service layer that coordinates analysis workflows.
repodoc/src/analysis/analysis_service.py - AST parser · Parses source into a common intermediate form for analysis.
repodoc/src/analysis/ast_parser.py - Call graph · Builds call relationships from parsed code.
repodoc/src/analysis/call_graph_analyzer.py - Deps · Derives dependency relationships between repository units.
repodoc/src/analysis/dependency_graphs_builder.py - Diffs · Computes repository changes for incremental refresh.
repodoc/src/analysis/diff_analysis.py - Lang analyzers · Language-specific analyzers for C, C++, C#, Go, Java, JavaScript, PHP, Python, Rust, and TypeScript.
repodoc/src/analysis/analyzers/python.py - Analysis model · Shared data structures for analysis results and entities.
repodoc/src/analysis/models/core.py
Graph
Core knowledge graph model and construction.
- Graph builder · Converts analysis output into the repository knowledge graph.
repodoc/src/graph/builder.py - Graph model · Core graph representation and entity relationships.
repodoc/src/graph/graph.py - Graph types · Typed graph entities and edge definitions.
repodoc/src/graph/models.py
Docs
LLM-backed documentation and clustering flow.
- Clustering · Groups related modules into higher-level documentation units.
repodoc/src/clustering/cluster_modules.py - Cluster prompts · Prompt templates supporting clustering decisions.
repodoc/src/clustering/prompts.py - Updater · Refreshes docs and graph from extracted changes.
repodoc/src/incremental/incremental_updater.py - Extractor · Extracts changed code for incremental processing.
repodoc/src/incremental/code_extractor.py
Runtime
Shared execution, tools, agents, and config.
- LLM · External model access and configuration-backed inference.
repodoc/src/llm.py - Skills · Reusable LLM tasks for code analysis, doc writing, and graph querying.
repodoc/src/skills/base.py - Tools · File, graph, and LLM tools exposed through common interfaces.
repodoc/src/tools/base.py - Agents · Agent base and factory for composing task-specific behaviors.
repodoc/src/agents/factory.py - Config · Application settings including LLM endpoint and model selection.
repodoc/src/config.py
Connections 26
- repodoc → Pipeline: invokes · CLI commands dispatch staged repository workflows.
- Pipeline → Analysis svc: coordinates · Pipeline starts by running repository analysis.
- Analysis svc → Repo analysis: uses · Service delegates repository inspection to the analyzer.
- Repo analysis → AST parser: parses · Source files are parsed into a common intermediate form.
- Repo analysis → Lang analyzers: dispatches · Language-specific analyzers normalize multi-language code.
- AST parser → Analysis model: emits · Parsed structures are represented in shared analysis models.
- Repo analysis → Call graph: builds · Analysis derives call relationships.
- Repo analysis → Deps: builds · Analysis derives dependency relationships.
- Repo analysis → Diffs: tracks · Change analysis supports incremental updates.
- Call graph → Analysis model: feeds · Call relationships become part of the analysis output.
- Deps → Analysis model: feeds · Dependency relationships become part of the analysis output.
- Analysis svc → Graph builder: hands off · Service passes analysis results to graph construction.
- Graph builder → Graph types: uses · Builder relies on graph entity and edge schemas.
- Graph builder → Graph model: populates · Graph builder materializes the knowledge graph.
- Pipeline → Clustering: optional · Pipeline can cluster related modules before doc generation.
- Clustering → Cluster prompts: guided by · Clustering decisions use prompt templates.
- Clustering → Graph model: reads · Clustering operates over the repository graph.
- Pipeline → Skills: uses · LLM tasks are packaged as skills.
- Skills → Tools: calls · Skills interact with file, graph, and LLM tools.
- Tools → LLM: wraps · LLM tool routes requests through the model client.
- Agents → Skills: orchestrates · Agents compose and run skill-driven tasks.
- Pipeline → Updater: update path · Incremental updates reuse the same pipeline boundary.
- Updater → Extractor: uses · Updater extracts changed code before recomputation.
- Extractor → Diffs: consumes · Changed regions are identified from diff analysis.
- LLM → Config: configured by · Model endpoint and credentials come from runtime config.
- Pipeline → Config: reads · Pipeline behavior depends on application settings.