How mishradeva/repoknowledge works
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 Generator · repo_crawler.py Crawler · cli.py CLI · java_parser.py Java parser
Components 17
Interface
User entry points and runtime configuration
Analysis pipeline
Discovery, parsing, synthesis, and orchestration
- Generator · Coordinates crawl, parse, Claude synthesis, and publishing
wiki_generator.py - Crawler · Selects repository files to analyze and filters noise
repo_crawler.py - Java parser · Extracts structured facts from Java and Spring sources
java_parser.py - Python parser · Extracts structured facts from Python sources
python_parser.py - TS parser · Extracts structured facts from TypeScript and Angular sources
ts_angular_parser.py - Parsed model · Shared normalized representation consumed by downstream analysis
- Three passes · Per-file, grouped/infrastructure, and system-level analysis flow
Publishing
Documentation output generation and formatting
- Markdown pub · Writes the primary wiki pages in Markdown
markdown_publisher.py - HTML pub · Optional HTML presentation backend
html_publisher.py - Docs wiki · Generated documentation tree under docs/wiki
- Wiki pages · Generated overview, architecture, API, data, infrastructure, and dependency pages
External systems
LLM and repository access dependencies
- Claude client · Wraps Anthropic Claude calls for higher-level synthesis
claude_client.py - Anthropic API · LLM service used for documentation synthesis
- GitHub PAT · Credential for private repo access and PR workflows in GitHub mode
Connections 20
- 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