Architecture

Summary

Wiki Bot is a modular Node.js CLI that automates GitHub wiki generation by chaining repository analysis, LLM prompting, and Git-backed publishing. The system emphasizes repeatable pipelines and incremental updates so architectural documentation stays aligned with the evolving codebase.

Architectural Pattern

• Style: Layered orchestration pipeline with integration adapters
• Key Technologies: Node.js (ESM), TypeScript, Anthropic Claude Agent SDK, Codex/Claude CLI fallbacks, Git CLI, filesystem streaming APIs

Key Directories

• src/: CLI entry point, configuration loading, logging, and the core orchestration workflow.
• src/github/: GitHub wiki persistence, including git clone/update and Markdown page management.
• src/prompts/: Prompt templates fed to the LLM for each documentation task and update mode.
• src/templates/: Markdown scaffolds applied to LLM outputs for consistent wiki formatting.
• .claude/: Local Agent SDK settings that tune provider behavior and authentication.
• backlog/: Roadmap and TODO tracking that informs planned CI and refinement features.

Architectural Areas

• CLI Orchestration & Runtime Control — src/index.ts, config.ts, and logging.ts parse CLI flags, load environment-driven configuration, establish logging, and sequence the full documentation run.
• Repository Discovery — repo-crawler.ts traverses the filesystem with ignore rules to emit a FileNode tree and flat file list used to scope documentation.
• LLM Provider Abstraction — query-factory.ts and mock-agent-sdk.ts select Anthropic SDK, Claude CLI, or Codex CLI, handle process spawning, and offer deterministic mocks for test mode.
• Documentation Synthesis — wiki-generator.ts, prompt-loader.ts, and template-renderer.ts assemble prompts, stream LLM responses, enforce outline completeness, and render final Markdown pages.
• Wiki Persistence & GitOps — github/git-repository-manager.ts and github/github-wiki-writer.ts manage cloning, cleaning, and pushing the GitHub wiki repository while generating navigation aids.

Component Interactions

• CLI bootstraps configuration, enables debug logging, and constructs a query function via createQueryFunction.
• RepoCrawler generates structure metadata consumed by WikiGenerator to contextualize LLM prompts and selective updates.
• WikiGenerator orchestrates home, architecture, and area documentation while delegating templating and existing content reuse.
• When wiki publishing is configured, GitHubWikiWriter stages page updates, manages sidebar regeneration, and commits through GitRepositoryManager.
• Debug logging captures prompt/response transcripts to aid iterative refinement without disrupting the main control flow.

Data Flow

• Repository files → RepoCrawler builds FileNode tree and file list for downstream targeting.
• Structure metadata + configuration → WikiGenerator composes prompts and depth instructions for the chosen LLM provider.
• Prompts → External LLM (Anthropic Agent SDK, Claude CLI, or Codex CLI) → Markdown drafts normalized by templates.
• Generated pages → Optional GitHubWikiWriter → Git operations that persist to the GitHub wiki remote.

Diagram

Diagram

graph TD
    I[CLI Runner] --> C[Config & Logger]
    I --> R[RepoCrawler]
    R --> G[WikiGenerator]
    G --> L[LLM Provider]
    G --> W[GitHub Wiki Repo]