ChangeGraph

The Problem

Maintaining documentation for actively developed repositories is a losing battle. READMEs go stale, architecture docs drift from reality, and changelogs are either missing or copy-pasted from commit messages. Teams need documentation that stays current, but nobody wants to write it manually after every sprint.

The Solution

We built ChangeGraph as a multi-agent system where specialized AI agents each own a documentation domain. A FastAPI backend orchestrates the agents, a React frontend provides the UI for triggering analysis and viewing results, and PostgreSQL stores the generated documentation history.

Key technical decisions:

• Domain-specialized agents — Separate agents for README generation, architecture analysis, API reference extraction, security auditing, and changelog compilation. Each agent has its own prompt engineering and output schema.
• Parallel agent orchestration — Agents that don't depend on each other's output run concurrently. The orchestrator builds a dependency graph and schedules independent agents in parallel batches.
• Repository parsing pipeline — Before agents run, a preprocessing step parses the repository structure, extracts file trees, identifies entry points, and builds a context map that agents can query without reading every file.
• Incremental analysis — On subsequent runs, only changed files are re-analyzed. The system diffs the current repo state against the last known state and routes only the affected sections to the relevant agents.

What Went Wrong

The initial implementation ran all agents sequentially — README agent first, then architecture, then API reference, and so on. Each agent took 10-20 seconds for an LLM call, so a full analysis of a medium repository took over a minute. For larger repos with more files to parse, it was approaching 3 minutes.

The fix: I redesigned the orchestration layer to model agent dependencies as a directed acyclic graph (DAG). The README and changelog agents depend on the repository context but not on each other. The architecture agent needs the file tree but not the API reference. By identifying these independence relationships, I could run 3-4 agents in parallel per batch.

This required careful handling of shared state — each agent needed its own copy of the repository context to avoid mutation conflicts. I used immutable data structures for the shared context and a producer-consumer pattern for writing results back to PostgreSQL.

Results

• 150% performance improvement over sequential execution
• Generates 5 documentation types from a single repository analysis
• Incremental mode reduces re-analysis time to seconds for small changes
• Scales to repositories with 1000+ files without context window overflow