Pipeline Architecture

Understanding how KodaDocs works under the hood helps you get the most out of it and troubleshoot issues.

Pipeline Steps

KodaDocs runs a 6-step pipeline, each building on the previous:

1. Discovery

Analyzes your project to find all user-facing routes and pages.

• Static analysis — scans directory structure based on your framework's conventions
• Service detection — identifies integrations like Stripe, Supabase, Clerk, Firebase, Auth0
• UI component inventory — detects shadcn/ui and similar component libraries
• Deployment platform detection — identifies Vercel, Cloudflare, Netlify, AWS
• Route metadata — classifies routes as dynamic/static, public/protected

Fallback: If static analysis finds too few routes, a Playwright browser crawler is launched.

2. Analysis

Extracts structured information from your source code using tree-sitter parsing.

• Code chunks — functions, classes, and modules from .js, .ts, .tsx, .py files
• Error patterns — throw new Error, raise, console.error, logger.error calls
• Data models — Prisma schemas and Drizzle ORM table definitions
• Product summary — AI-generated description of what your app does (if AI enabled)

This step is fully deterministic (no AI calls) except for the optional product summary.

3. Capture

Takes screenshots of every discovered route using headless Chromium via Playwright.

• Authentication — auto-fills login forms using smart detection
• Reachability check — verifies your app is running before attempting capture
• Full-page screenshots — captures the entire scrollable page
• Entropy validation — rejects blank or broken screenshots
• PII detection — identifies sensitive regions (emails, phone numbers, API keys)
• DOM extraction — records positions of buttons, links, headings, and images

If your app isn't running, this step is skipped gracefully.

4. Annotation

Enhances screenshots with numbered callout circles on interactive elements.

• PII blurring — applies Gaussian blur to sensitive regions before annotating
• Element selection — picks the 15 most relevant interactive elements per page
• Deduplication — removes duplicate elements by name and position
• Numbered callouts — draws circles with your brand color

5. Enrichment

Generates documentation articles using AI (Claude).

• Article planning — Claude Sonnet analyzes the full context and creates an article outline
• Content generation — Claude Haiku writes each article with screenshot references
• Quality validation — checks for banned phrases and rates confidence (0.0–1.0)
• Service-aware suggestions — automatically adds billing guides if Stripe is detected, etc.

6. Output

Assembles everything into a VitePress static site.

• Article files — Markdown files with frontmatter
• Screenshot assets — copied to docs/assets/
• VitePress config — sidebar navigation, theme settings
• Theme CSS — brand color variables, theme preset styles
• Static build — runs npm install && npm run docs:build

Resumption

Every step saves its results to .kodadocs/run_manifest.json. If the pipeline is interrupted:

• Re-running kodadocs generate automatically skips completed steps
• A config change (detected via hash) triggers a fresh run
• Use --fresh to force a complete re-run

Cost Tracking

KodaDocs tracks estimated API costs throughout the pipeline:

• Sonnet is used for understanding (product summary, article planning) — higher quality, higher cost
• Haiku is used for generation (article content) — fast and economical
• Total cost is displayed at the end of the pipeline run