# sysuselab/repodoc architecture

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

- Interactive diagram: https://gitdiagram.com/sysuselab/repodoc
- Repository: https://github.com/sysuselab/repodoc

## Overview

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: [`repodoc/pipeline/generator.py`](https://github.com/sysuselab/repodoc/blob/main/repodoc/pipeline/generator.py) (Pipeline), [`repodoc/src/analysis/repo_analyzer.py`](https://github.com/sysuselab/repodoc/blob/main/repodoc/src/analysis/repo_analyzer.py) (Repo analysis), [`repodoc/src/analysis/analysis_service.py`](https://github.com/sysuselab/repodoc/blob/main/repodoc/src/analysis/analysis_service.py) (Analysis svc), [`repodoc/src/graph/builder.py`](https://github.com/sysuselab/repodoc/blob/main/repodoc/src/graph/builder.py) (Graph builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_repodoc_cli["repodoc<br/>CLI entrypoint<br/>[commands.py]"]
  node_pipeline_generator["Pipeline<br/>orchestrator<br/>[generator.py]"]
end

subgraph group_analysis["Analysis"]
  node_repo_analyzer["Repo analysis<br/>repo analyzer<br/>[repo_analyzer.py]"]
  node_analysis_service["Analysis svc<br/>analysis service"]
  node_ast_parser["AST parser<br/>parser core<br/>[ast_parser.py]"]
  node_call_graph["Call graph<br/>graph analysis"]
  node_dep_graph["Deps<br/>graph analysis"]
  node_diff_analysis["Diffs<br/>change analysis<br/>[diff_analysis.py]"]
  node_lang_analyzers["Lang analyzers<br/>multi-language analyzers<br/>[python.py]"]
  node_analysis_models["Analysis model<br/>core model<br/>[core.py]"]
end

subgraph group_graph["Graph"]
  node_graph_builder["Graph builder<br/>[builder.py]"]
  node_graph_model[("Graph model<br/>graph store<br/>[graph.py]")]
  node_graph_models["Graph types<br/>graph schema<br/>[models.py]"]
end

subgraph group_docs["Docs"]
  node_cluster_modules["Clustering<br/>[cluster_modules.py]"]
  node_clustering_prompts["Cluster prompts<br/>prompt assets<br/>[prompts.py]"]
  node_incremental_updater["Updater<br/>incremental update"]
  node_code_extractor["Extractor<br/>[code_extractor.py]"]
end

subgraph group_runtime["Runtime"]
  node_llm_core(("LLM<br/>model client<br/>[llm.py]"))
  node_skills["Skills<br/>[base.py]"]
  node_tools["Tools<br/>tooling layer<br/>[base.py]"]
  node_agents["Agents<br/>agent layer<br/>[factory.py]"]
  node_config["Config<br/>[config.py]"]
end

node_repodoc_cli -->|"invokes"| node_pipeline_generator
node_pipeline_generator -->|"coordinates"| node_analysis_service
node_analysis_service -->|"uses"| node_repo_analyzer
node_repo_analyzer -->|"parses"| node_ast_parser
node_repo_analyzer -->|"dispatches"| node_lang_analyzers
node_ast_parser -->|"emits"| node_analysis_models
node_repo_analyzer -->|"builds"| node_call_graph
node_repo_analyzer -->|"builds"| node_dep_graph
node_repo_analyzer -->|"tracks"| node_diff_analysis
node_call_graph -->|"feeds"| node_analysis_models
node_dep_graph -->|"feeds"| node_analysis_models
node_analysis_service -->|"hands off"| node_graph_builder
node_graph_builder -->|"uses"| node_graph_models
node_graph_builder -->|"populates"| node_graph_model
node_pipeline_generator -->|"optional"| node_cluster_modules
node_cluster_modules -->|"guided by"| node_clustering_prompts
node_cluster_modules -->|"reads"| node_graph_model
node_pipeline_generator -->|"uses"| node_skills
node_skills -->|"calls"| node_tools
node_tools -->|"wraps"| node_llm_core
node_agents -->|"orchestrates"| node_skills
node_pipeline_generator -->|"update path"| node_incremental_updater
node_incremental_updater -->|"uses"| node_code_extractor
node_code_extractor -->|"consumes"| node_diff_analysis
node_llm_core -->|"configured by"| node_config
node_pipeline_generator -->|"reads"| node_config

click node_repodoc_cli "https://github.com/sysuselab/repodoc/blob/main/repodoc/cli/commands.py"
click node_pipeline_generator "https://github.com/sysuselab/repodoc/blob/main/repodoc/pipeline/generator.py"
click node_repo_analyzer "https://github.com/sysuselab/repodoc/blob/main/repodoc/src/analysis/repo_analyzer.py"
click node_analysis_service "https://github.com/sysuselab/repodoc/blob/main/repodoc/src/analysis/analysis_service.py"
click node_ast_parser "https://github.com/sysuselab/repodoc/blob/main/repodoc/src/analysis/ast_parser.py"
click node_call_graph "https://github.com/sysuselab/repodoc/blob/main/repodoc/src/analysis/call_graph_analyzer.py"
click node_dep_graph "https://github.com/sysuselab/repodoc/blob/main/repodoc/src/analysis/dependency_graphs_builder.py"
click node_diff_analysis "https://github.com/sysuselab/repodoc/blob/main/repodoc/src/analysis/diff_analysis.py"
click node_lang_analyzers "https://github.com/sysuselab/repodoc/blob/main/repodoc/src/analysis/analyzers/python.py"
click node_analysis_models "https://github.com/sysuselab/repodoc/blob/main/repodoc/src/analysis/models/core.py"
click node_graph_builder "https://github.com/sysuselab/repodoc/blob/main/repodoc/src/graph/builder.py"
click node_graph_model "https://github.com/sysuselab/repodoc/blob/main/repodoc/src/graph/graph.py"
click node_graph_models "https://github.com/sysuselab/repodoc/blob/main/repodoc/src/graph/models.py"
click node_cluster_modules "https://github.com/sysuselab/repodoc/blob/main/repodoc/src/clustering/cluster_modules.py"
click node_clustering_prompts "https://github.com/sysuselab/repodoc/blob/main/repodoc/src/clustering/prompts.py"
click node_llm_core "https://github.com/sysuselab/repodoc/blob/main/repodoc/src/llm.py"
click node_skills "https://github.com/sysuselab/repodoc/blob/main/repodoc/src/skills/base.py"
click node_tools "https://github.com/sysuselab/repodoc/blob/main/repodoc/src/tools/base.py"
click node_agents "https://github.com/sysuselab/repodoc/blob/main/repodoc/src/agents/factory.py"
click node_incremental_updater "https://github.com/sysuselab/repodoc/blob/main/repodoc/src/incremental/incremental_updater.py"
click node_code_extractor "https://github.com/sysuselab/repodoc/blob/main/repodoc/src/incremental/code_extractor.py"
click node_config "https://github.com/sysuselab/repodoc/blob/main/repodoc/src/config.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_repodoc_cli,node_pipeline_generator toneBlue
class node_repo_analyzer,node_analysis_service,node_ast_parser,node_call_graph,node_dep_graph,node_diff_analysis,node_lang_analyzers,node_analysis_models toneAmber
class node_graph_builder,node_graph_model,node_graph_models toneMint
class node_cluster_modules,node_clustering_prompts,node_incremental_updater,node_code_extractor toneRose
class node_llm_core,node_skills,node_tools,node_agents,node_config toneIndigo
```

## Components

### CLI

Command surface and pipeline entry points.

- [repodoc](https://github.com/sysuselab/repodoc/blob/main/repodoc/cli/commands.py): CLI entrypoint · Top-level command interface for analyze, cluster, docs, generate, and update. · `repodoc/cli/commands.py`
- [Pipeline](https://github.com/sysuselab/repodoc/blob/main/repodoc/pipeline/generator.py): orchestrator · Coordinates analysis, graph building, clustering, and doc generation. · `repodoc/pipeline/generator.py`

### Analysis

Static repository understanding and derived structure.

- [Repo analysis](https://github.com/sysuselab/repodoc/blob/main/repodoc/src/analysis/repo_analyzer.py): repo analyzer · Runs repository-wide analysis and dispatches language-specific parsing. · `repodoc/src/analysis/repo_analyzer.py`
- [Analysis svc](https://github.com/sysuselab/repodoc/blob/main/repodoc/src/analysis/analysis_service.py): analysis service · Service layer that coordinates analysis workflows. · `repodoc/src/analysis/analysis_service.py`
- [AST parser](https://github.com/sysuselab/repodoc/blob/main/repodoc/src/analysis/ast_parser.py): parser core · Parses source into a common intermediate form for analysis. · `repodoc/src/analysis/ast_parser.py`
- [Call graph](https://github.com/sysuselab/repodoc/blob/main/repodoc/src/analysis/call_graph_analyzer.py): graph analysis · Builds call relationships from parsed code. · `repodoc/src/analysis/call_graph_analyzer.py`
- [Deps](https://github.com/sysuselab/repodoc/blob/main/repodoc/src/analysis/dependency_graphs_builder.py): graph analysis · Derives dependency relationships between repository units. · `repodoc/src/analysis/dependency_graphs_builder.py`
- [Diffs](https://github.com/sysuselab/repodoc/blob/main/repodoc/src/analysis/diff_analysis.py): change analysis · Computes repository changes for incremental refresh. · `repodoc/src/analysis/diff_analysis.py`
- [Lang analyzers](https://github.com/sysuselab/repodoc/blob/main/repodoc/src/analysis/analyzers/python.py): multi-language analyzers · Language-specific analyzers for C, C++, C#, Go, Java, JavaScript, PHP, Python, Rust, and TypeScript. · `repodoc/src/analysis/analyzers/python.py`
- [Analysis model](https://github.com/sysuselab/repodoc/blob/main/repodoc/src/analysis/models/core.py): core model · Shared data structures for analysis results and entities. · `repodoc/src/analysis/models/core.py`

### Graph

Core knowledge graph model and construction.

- [Graph builder](https://github.com/sysuselab/repodoc/blob/main/repodoc/src/graph/builder.py): graph builder · Converts analysis output into the repository knowledge graph. · `repodoc/src/graph/builder.py`
- [Graph model](https://github.com/sysuselab/repodoc/blob/main/repodoc/src/graph/graph.py): graph store · Core graph representation and entity relationships. · `repodoc/src/graph/graph.py`
- [Graph types](https://github.com/sysuselab/repodoc/blob/main/repodoc/src/graph/models.py): graph schema · Typed graph entities and edge definitions. · `repodoc/src/graph/models.py`

### Docs

LLM-backed documentation and clustering flow.

- [Clustering](https://github.com/sysuselab/repodoc/blob/main/repodoc/src/clustering/cluster_modules.py): module clustering · Groups related modules into higher-level documentation units. · `repodoc/src/clustering/cluster_modules.py`
- [Cluster prompts](https://github.com/sysuselab/repodoc/blob/main/repodoc/src/clustering/prompts.py): prompt assets · Prompt templates supporting clustering decisions. · `repodoc/src/clustering/prompts.py`
- [Updater](https://github.com/sysuselab/repodoc/blob/main/repodoc/src/incremental/incremental_updater.py): incremental update · Refreshes docs and graph from extracted changes. · `repodoc/src/incremental/incremental_updater.py`
- [Extractor](https://github.com/sysuselab/repodoc/blob/main/repodoc/src/incremental/code_extractor.py): change extractor · Extracts changed code for incremental processing. · `repodoc/src/incremental/code_extractor.py`

### Runtime

Shared execution, tools, agents, and config.

- [LLM](https://github.com/sysuselab/repodoc/blob/main/repodoc/src/llm.py): model client · External model access and configuration-backed inference. · `repodoc/src/llm.py`
- [Skills](https://github.com/sysuselab/repodoc/blob/main/repodoc/src/skills/base.py): prompt skills · Reusable LLM tasks for code analysis, doc writing, and graph querying. · `repodoc/src/skills/base.py`
- [Tools](https://github.com/sysuselab/repodoc/blob/main/repodoc/src/tools/base.py): tooling layer · File, graph, and LLM tools exposed through common interfaces. · `repodoc/src/tools/base.py`
- [Agents](https://github.com/sysuselab/repodoc/blob/main/repodoc/src/agents/factory.py): agent layer · Agent base and factory for composing task-specific behaviors. · `repodoc/src/agents/factory.py`
- [Config](https://github.com/sysuselab/repodoc/blob/main/repodoc/src/config.py): runtime config · Application settings including LLM endpoint and model selection. · `repodoc/src/config.py`

## Connections

- 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.