How repowise works, end to end.

The Big Picture

repowise takes a codebase and produces living documentation: AI-generated documentation that stays current as the code changes. Each layer has a single responsibility and a clear boundary.

Ingestion Pipeline

The ingestion pipeline turns raw source code into structured data. Five components run in sequence.

FileTraverser

Walks the directory tree and applies three filter layers to find only documentable files.

ASTParser

Extracts functions, classes, imports, and exports from 28 languages using tree-sitter queries with unified capture names.

@symbol.def      : full definition node (provides line numbers)
@symbol.name     : the name identifier
@symbol.params   : parameter list
@symbol.modifiers : decorators, visibility keywords
@import.statement : full import node
@import.module   : the module path being imported

Adding a new language requires only one .scm query file and one entry in LANGUAGE_CONFIGS.

GitIndexer

Extracts ownership, churn, co-change relationships, and significant commits from git history using a single git log pass, O(1) processes instead of O(N).

ChangeDetector

After the initial indexing, ChangeDetector determines what to regenerate on each update run.

Generation Pipeline

The generation pipeline takes ingested data and produces documentation pages using LLMs.

Page Types & Levels

repowise generates 10 page types in 8 ordered levels. Later levels depend on earlier ones: a module page references the file pages inside it.

ContextAssembler

Each page type has a ContextAssembler method that builds everything the LLM needs to know. Context is rendered into Jinja2 templates and token-budgeted to fit the LLM window.

FilePageContext
├── file_path, language
├── symbols (public first, then private)
│   └── name, kind, signature, docstring, visibility
├── imports, exports
├── dependencies + dependents
├── file_source_snippet (trimmed to token budget)
├── pagerank_score, betweenness_score, community_id
├── git_metadata (ownership, churn, significant commits)
├── co_change_pages
├── dead_code_findings
├── depth: "minimal" | "standard" | "thorough"
└── rag_context (related pages from vector search)

Job System

The job system checkpoints every page, so a long run on a large repository resumes exactly where it stopped.

{
  "status": "running",
  "total_pages": 300,
  "completed_pages": 150,
  "completed_page_ids": ["file_page:src/auth.py", "..."],
  "current_level": 2
}

Persistence Layer

repowise writes to three independent stores: SQL, vector store, and graph, each tuned for its own query pattern.

Graph Algorithms

Every graph metric is computed from the import dependency graph: a directed graph where each node is a file and each edge is an import.

PageRank

Answers “How important is this file?” A file is important if many other important files depend on it.

score(B) = (1 - α) / N  +  α × Σ [ score(A) / out_degree(A) ]
                                        for each A that imports B

α = 0.85 (damping factor: probability of following an edge vs. teleporting)

• Doc priority: highest PageRank files get documentation pages generated first
• Generation depth: low PageRank + low churn → “minimal” docs (saves LLM tokens)
• CLAUDE.md: files sorted by PageRank descending, most important appears first for AI assistants

Betweenness Centrality

Answers “Is this file a bridge between subsystems?” High betweenness files sit on shortest paths connecting many file pairs: they are the joints that hold subsystems together.

Community Detection

Louvain algorithm on the undirected graph finds natural clusters: files that are more connected to each other than to the rest. These clusters become subsystem labels in the documentation and color groups in the dependency graph visualization.

Dead Code Detection

Files with in-degree = 0 (nothing imports them) are dead code candidates. repowise filters out entry points, test files, config files, and framework-loaded files before flagging, then scores confidence using git activity.

MCP Tools

Ten MCP tools expose all of repowise's intelligence to AI coding assistants: Claude Code, Cursor, Cline, and any MCP-compatible editor.

Safeguards

Every layer checks its own output, so the docs, the graph and the three stores stay accurate as the code moves.

• Graph-first architecture captures structural dependencies that keyword search misses.
• Git history and co-change add a time dimension that static analysis alone cannot see.
• A bounded cascade with PageRank-sorted budgets keeps the most important pages fresh.
• Decision mining reads architectural intent from commits, comments and documentation.
• MCP puts all of it inside the AI coding workflow, with no copy and paste.

1. doctor --repairChecks the SQL, vector and full-text stores against each other and repairs any orphaned entry.
2. Symbol cross-checkValidates generated pages against the symbols the parser actually found.
3. Framework edgesAdds the edges pytest, Django, FastAPI and Flask create at runtime, so dynamic loading stays in the graph.
4. Adaptive cascade budgetScales regeneration from 10 to 50 pages with the size of the change.
5. Generation reportSummarises cost and quality after every update run.