# mishradeva/repoknowledge architecture

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

- Interactive diagram: https://gitdiagram.com/mishradeva/repoknowledge
- Repository: https://github.com/mishradeva/repoknowledge

## Overview

1. **What this repository is**
   - RepoWiki is a **Python-based documentation generator** that scans a source repository, extracts structure from code, asks Anthropic Claude to synthesize higher-level understanding, and writes a DeepWiki-style documentation set back into the repo.

2. **Main entry points**
   - `cli.py` is the user-facing command-line entry point.
   - `wiki_generator.py` is the central orchestrator that ties together crawling, parsing, LLM analysis, and publishing.
   - The repo is designed to run in two modes: **local repo analysis** and **remote GitHub repo analysis**.

3. **Repository discovery layer**
   - `repo_crawler.py` is responsible for walking the target repository and selecting files to analyze.
   - It focuses on source and infrastructure artifacts, while skipping build outputs and other noise.
   - This layer defines the first important boundary in the architecture: **filesystem repository contents in, curated analysis set out**.

4. **Language-specific parsing layer**
   - Parsing is split by language/domain into `java_parser.py`, `python_parser.py`, and `ts_angular_parser.py`.
   - These modules extract a shared intermediate representation from source files, such as classes, methods, annotations, endpoints, and dependency relationships.
   - The repo’s primary documented target is Java/Spring Boot, but the parser architecture is intentionally extensible.

5. **Shared analysis model**
   - The parsers do not directly generate docs; they normalize source files into a common parsed-file structure used by downstream stages.
   - This makes the rest of the pipeline largely language-agnostic, which is why the same generator can support Java, Python, and TypeScript/Angular inputs.

6. **LLM analysis boundary**
   - `claude_client.py` encapsulates calls to Anthropic’s Claude API.
   - The repository uses Claude as an external reasoning layer to convert parsed code facts into architectural summaries, service groupings, and documentation narratives.
   - The readme describes a **three-pass flow**: per-file summaries, grouped/infrastructure analysis, then system-level architecture synthesis.

7. **Documentation generation**
   - `markdown_publisher.py` and `html_publisher.py` are the publishing backends.
   - Markdown is the primary output format, producing wiki pages such as `index.md`, `architecture.md`, `api-reference.md`, `data-models.md`, `infrastructure.md`, and `dependencies.md`.
   - HTML publishing exists as an alternate presentation layer, but the repo’s core artifact is the Markdown wiki set.

8. **Output structure and documentation boundaries**
   - The generated docs are organized into a coherent documentation tree under `docs/wiki/`.
   - Different pages correspond to different architectural concerns: overview, system design, component deep dives, API surface, data model, infrastructure, and dependency graphs.
   - This separation is important for diagramming because it reflects distinct source-to-output transformations rather than one monolithic report.

9. **External services and operational dependencies**
   - The tool depends on the **Anthropic API key** for LLM analysis.
   - In GitHub mode it also needs a **GitHub PAT** to fetch private repositories and/or support PR-based publishing workflows.
   - These are the only material external systems in the architecture: one for intelligence, one for repository access and CI integration.

10. **Configuration and runtime**
   - The repo is a **Python 3.10+** application with dependencies listed in `requirements.txt`.
   - `repowiki.yml` serves as configuration for repository analysis/publishing behavior.
   - The README emphasizes caching by file hash, which reduces repeated Claude usage on unchanged files.

11. **CI/CD usage pattern**
   - The architecture supports automated regeneration on repository pushes, typically by running in a GitHub Actions workflow.
   - In this mode, the tool updates `docs/wiki/` and can open a pull request with regenerated documentation.
   - This makes the publishing step part of the repo’s delivery pipeline rather than a one-off local tool.

12. **End-to-end data flow**
   - The overall flow is: **crawl repo files → parse source into structured facts → send facts to Claude for synthesis → generate markdown/html docs → write/publish the wiki output**.
   - The clearest architectural boundary is between deterministic code analysis and probabilistic LLM synthesis, with publishing as the final I/O layer.

Main entry points: [`wiki_generator.py`](https://github.com/mishradeva/repoknowledge/blob/main/wiki_generator.py) (Generator), [`repo_crawler.py`](https://github.com/mishradeva/repoknowledge/blob/main/repo_crawler.py) (Crawler), [`cli.py`](https://github.com/mishradeva/repoknowledge/blob/main/cli.py) (CLI), [`java_parser.py`](https://github.com/mishradeva/repoknowledge/blob/main/java_parser.py) (Java parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_interface["Interface"]
  node_cli["CLI<br/>entrypoint<br/>[cli.py]"]
  node_repowiki_config["Config<br/>[repowiki.yml]"]
  node_requirements["Deps<br/>[requirements.txt]"]
end

subgraph group_group_pipeline["Analysis pipeline"]
  node_wiki_generator["Generator<br/>orchestrator<br/>[wiki_generator.py]"]
  node_repo_crawler["Crawler<br/>discovery<br/>[repo_crawler.py]"]
  node_java_parser["Java parser<br/>[java_parser.py]"]
  node_python_parser["Python parser<br/>[python_parser.py]"]
  node_ts_angular_parser["TS parser"]
  node_parsed_model["Parsed model<br/>intermediate schema"]
  node_analysis_passes{{"Three passes<br/>synthesis stages"}}
end

subgraph group_group_publish["Publishing"]
  node_markdown_publisher["Markdown pub<br/>publisher"]
  node_html_publisher["HTML pub<br/>publisher<br/>[html_publisher.py]"]
  node_docs_wiki[("Docs wiki<br/>output tree")]
  node_wiki_pages["Wiki pages<br/>wiki set"]
end

subgraph group_group_external["External systems"]
  node_claude_client["Claude client<br/>llm adapter<br/>[claude_client.py]"]
  node_anthropic_api(("Anthropic API<br/>external service"))
  node_github_pat(("GitHub PAT<br/>access token"))
end

node_cli -->|"starts"| node_wiki_generator
node_repowiki_config -->|"configures"| node_wiki_generator
node_cli -->|"depends on"| node_requirements
node_wiki_generator -->|"discovers"| node_repo_crawler
node_repo_crawler -->|"routes"| node_java_parser
node_repo_crawler -->|"routes"| node_python_parser
node_repo_crawler -->|"routes"| node_ts_angular_parser
node_java_parser -->|"normalizes"| node_parsed_model
node_python_parser -->|"normalizes"| node_parsed_model
node_ts_angular_parser -->|"normalizes"| node_parsed_model
node_wiki_generator -->|"orchestrates"| node_analysis_passes
node_parsed_model -->|"feeds"| node_analysis_passes
node_analysis_passes -->|"queries"| node_claude_client
node_claude_client -->|"calls"| node_anthropic_api
node_wiki_generator -->|"publishes"| node_markdown_publisher
node_wiki_generator -->|"publishes"| node_html_publisher
node_markdown_publisher -->|"writes"| node_docs_wiki
node_html_publisher -->|"renders"| node_docs_wiki
node_docs_wiki -->|"contains"| node_wiki_pages
node_wiki_generator -->|"uses"| node_github_pat

click node_cli "https://github.com/mishradeva/repoknowledge/blob/main/cli.py"
click node_wiki_generator "https://github.com/mishradeva/repoknowledge/blob/main/wiki_generator.py"
click node_repowiki_config "https://github.com/mishradeva/repoknowledge/blob/main/repowiki.yml"
click node_requirements "https://github.com/mishradeva/repoknowledge/blob/main/requirements.txt"
click node_repo_crawler "https://github.com/mishradeva/repoknowledge/blob/main/repo_crawler.py"
click node_java_parser "https://github.com/mishradeva/repoknowledge/blob/main/java_parser.py"
click node_python_parser "https://github.com/mishradeva/repoknowledge/blob/main/python_parser.py"
click node_ts_angular_parser "https://github.com/mishradeva/repoknowledge/blob/main/ts_angular_parser.py"
click node_claude_client "https://github.com/mishradeva/repoknowledge/blob/main/claude_client.py"
click node_markdown_publisher "https://github.com/mishradeva/repoknowledge/blob/main/markdown_publisher.py"
click node_html_publisher "https://github.com/mishradeva/repoknowledge/blob/main/html_publisher.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_repowiki_config,node_requirements toneBlue
class node_wiki_generator,node_repo_crawler,node_java_parser,node_python_parser,node_ts_angular_parser,node_parsed_model,node_analysis_passes toneAmber
class node_markdown_publisher,node_html_publisher,node_docs_wiki,node_wiki_pages toneMint
class node_claude_client,node_anthropic_api,node_github_pat toneRose
```

## Components

### Interface

User entry points and runtime configuration

- [CLI](https://github.com/mishradeva/repoknowledge/blob/main/cli.py): entrypoint · Command-line entry point for running RepoWiki · `cli.py`
- [Config](https://github.com/mishradeva/repoknowledge/blob/main/repowiki.yml): runtime config · Controls repository analysis and publishing behavior · `repowiki.yml`
- [Deps](https://github.com/mishradeva/repoknowledge/blob/main/requirements.txt): python deps · Python package dependencies for the application · `requirements.txt`

### Analysis pipeline

Discovery, parsing, synthesis, and orchestration

- [Generator](https://github.com/mishradeva/repoknowledge/blob/main/wiki_generator.py): orchestrator · Coordinates crawl, parse, Claude synthesis, and publishing · `wiki_generator.py`
- [Crawler](https://github.com/mishradeva/repoknowledge/blob/main/repo_crawler.py): discovery · Selects repository files to analyze and filters noise · `repo_crawler.py`
- [Java parser](https://github.com/mishradeva/repoknowledge/blob/main/java_parser.py): parser · Extracts structured facts from Java and Spring sources · `java_parser.py`
- [Python parser](https://github.com/mishradeva/repoknowledge/blob/main/python_parser.py): parser · Extracts structured facts from Python sources · `python_parser.py`
- [TS parser](https://github.com/mishradeva/repoknowledge/blob/main/ts_angular_parser.py): parser · Extracts structured facts from TypeScript and Angular sources · `ts_angular_parser.py`
- **Parsed model**: intermediate schema · Shared normalized representation consumed by downstream analysis
- **Three passes**: synthesis stages · Per-file, grouped/infrastructure, and system-level analysis flow

### Publishing

Documentation output generation and formatting

- [Markdown pub](https://github.com/mishradeva/repoknowledge/blob/main/markdown_publisher.py): publisher · Writes the primary wiki pages in Markdown · `markdown_publisher.py`
- [HTML pub](https://github.com/mishradeva/repoknowledge/blob/main/html_publisher.py): publisher · Optional HTML presentation backend · `html_publisher.py`
- **Docs wiki**: output tree · Generated documentation tree under docs/wiki
- **Wiki pages**: wiki set · Generated overview, architecture, API, data, infrastructure, and dependency pages

### External systems

LLM and repository access dependencies

- [Claude client](https://github.com/mishradeva/repoknowledge/blob/main/claude_client.py): llm adapter · Wraps Anthropic Claude calls for higher-level synthesis · `claude_client.py`
- **Anthropic API**: external service · LLM service used for documentation synthesis
- **GitHub PAT**: access token · Credential for private repo access and PR workflows in GitHub mode

## Connections

- CLI → Generator: starts · CLI invokes the generation pipeline
- Config → Generator: configures · Runtime settings influence discovery, analysis, and publishing
- CLI → Deps: depends on · Python runtime dependencies
- Generator → Crawler: discovers · Finds files eligible for documentation analysis
- Crawler → Java parser: routes · Sends Java sources to the Java parser
- Crawler → Python parser: routes · Sends Python sources to the Python parser
- Crawler → TS parser: routes · Sends TypeScript and Angular sources to the TS parser
- Java parser → Parsed model: normalizes · Emits shared structured facts
- Python parser → Parsed model: normalizes · Emits shared structured facts
- TS parser → Parsed model: normalizes · Emits shared structured facts
- Generator → Three passes: orchestrates · Coordinates the three-stage synthesis flow
- Parsed model → Three passes: feeds · Structured code facts drive the synthesis stages
- Three passes → Claude client: queries · Uses Claude to synthesize documentation narratives
- Claude client → Anthropic API: calls · External LLM API dependency
- Generator → Markdown pub: publishes · Produces Markdown wiki artifacts
- Generator → HTML pub: publishes · Produces optional HTML output
- Markdown pub → Docs wiki: writes · Generates the documentation tree
- HTML pub → Docs wiki: renders · Alternative presentation layer over generated content
- Docs wiki → Wiki pages: contains · Generated documentation pages and sections
- Generator → GitHub PAT: uses · Needed in GitHub mode for private repo access or PR workflows
