Built this while working across multiple microservice codebases — would love feedback from folks solving similar problems.
The Problem
Architecture documentation tends to drift over time.
It’s usually written once, when the system is simpler. But as the code evolves — refactors, new services, changing APIs, updated data flows — the documentation doesn’t keep up.
Updating architecture docs is not trivial. It often requires re-understanding the system end-to-end, tracing dependencies, and reconstructing how components interact. In practice, this rarely happens alongside regular development work.
Over time, this creates familiar challenges:
- New engineers take longer to ramp up
- “Safe” changes can impact downstream systems unexpectedly
- Code reviews focus on diffs, not system-wide effects
- Important system knowledge lives in people’s heads
The architecture knowledge does exist — it’s all in the code.
But it’s distributed across many files and not easily accessible as a whole.
What I Built: Archexa
To address this, I built Archexa — a CLI tool that analyzes a codebase and generates structured engineering artifacts directly from it.
Instead of maintaining documentation manually, Archexa generates it on demand.
It produces:
- Architecture documentation - (component maps, dependency diagrams, communication flows)
- Change impact analysis- (likely downstream effects before merging changes)
- Architecture-aware code reviews - (cross-file and cross-service insights)
- Deep technical Q&A - (structured answers to system-level questions)
Not just docstrings or README templates — actual architecture documents, with references back to source files.
Quick Start
Install (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/ereshzealous/archexa/main/install.sh | bash
### Initialize config
archexa init
### Get an overview of your codebase
archexa gist
For Detailed Documentation Please visit - github
Why Archexa
This tool comes from recurring patterns I’ve seen in real projects:
Onboarding takes too long - Understanding how a system fits together often requires exploring many files manually. That knowledge is rarely centralized.
Changes have hidden impact - A small change — like renaming a field — can affect consumers elsewhere (APIs, events, downstream services) that aren’t obvious from local context.
Code reviews miss system-level effects - Reviews are typically scoped to changed files. But system behavior often depends on interactions beyond that diff.
All of these stem from the same root issue - The architecture exists in the code, but it’s not easily visible as a system.
Where Existing Tools Fit
There are strong tools in this space, each solving part of the problem:
Each of these tools is valuable.
Archexa focuses on combining into a single workflow.
- code analysis
- LLM-based reasoning
- structured output
- CLI-first workflow
Two Modes: Fast vs Deep
Not every question needs the same depth.
Pipeline Mode (Default)
- Scans entire codebase using AST parsing
- Extracts structure: imports, classes, APIs, data flows
- Generates a system-level overview
Performance:
- 1–2 AI calls
- Seconds to minutes
- Low cost
Agent Mode (--deep)
- Reads actual source files
- Traces dependencies and execution paths
- Follows relationships across components
Behavior:
- Multiple tool calls (10–50)
- More detailed insights
- Higher cost
Example (FastAPI — 2,600+ files)
When analyzing dependency injection:
- Pipeline mode → high-level overview
- Deep mode → traced execution path, identified patterns, documented lifecycle, cited source files
Six Commands, Six Use Cases
gist — Codebase Overview
archexa gist --config archexa.yaml
archexa gist --config archexa.yaml --deep
Quick understanding of - architecture, components, request flow
query — Ask Questions
archexa query --config archexa.yaml --query "How does authentication work?"
archexa query --config archexa.yaml --query "Explain dependency injection" --deep
Returns structured answers with file references.
analyze — Full Architecture Docs
archexa analyze --config archexa.yaml
Generates:
- Mermaid architecture diagrams
- Component tables with responsibilities
- Dependency maps and communication flows
impact — Change Impact Analysis
archexa impact --config archexa.yaml --target "src/routing.py" --query "Adding rate limiting parameter"
Surfaces:
- Directly and transitively affected files
- Likely downstream impact across services
- Risk assessment and migration strategy
review — Architecture-Aware Review
archexa review --config archexa.yaml --changed --deep
archexa review --config archexa.yaml --branch origin/main..HEAD --deep
Identifies:
- Cross-file issues and contract mismatches
- System-level concerns (security, performance, error handling)
- Areas worth deeper inspection — with exact file and line numbers
chat — Interactive Exploration
archexa chat --config archexa.yaml
- Ask questions in plain English
- Switch between fast and deep mode per turn
- Maintain context across turns
- Save sessions to file with
/save
Works With Multiple LLM Providers
Archexa connects via OpenAI-compatible endpoints, so you can use the provider that works best for you.
- OpenAI — GPT-4o, GPT-4.1
- Anthropic — Claude Sonnet, Claude Haiku (via OpenRouter)
- Google — Gemini Flash (via OpenRouter)
- Azure OpenAI
- Ollama — fully local, free, code never leaves your machine
- Any OpenAI-compatible endpoint — LM Studio, vLLM, corporate proxies
The FastAPI examples in the repo use three different models so you can compare quality across providers.
Single Binary, Runs Locally
Archexa ships as a single binary. No Python install, no package manager — download and run.
curl -fsSL https://raw.githubusercontent.com/ereshzealous/archexa/main/install.sh | bash
- macOS (ARM/Intel), Linux (x64/ARM).
- windows - Download .exe file manually from releases
Your code stays on your machine. Only extracted evidence goes to the AI API — not your raw source files. Or use Ollama and nothing leaves your machine at all.
A local CLI has a different risk profile from SaaS tools — it stays in your workflow without depending on a hosted product's availability or roadmap decisions.
Real Output: FastAPI (2,661 files)
Every command run against a real open-source project, with configs and generated documents published
| Command | Mode | Model | Time | Output |
|---|---|---|---|---|
gist |
Pipeline | Gemini Flash | 1m 41s | 7.5 KB overview |
gist --deep |
Agent | Gemini Flash | 58s | 10 KB with file refs |
analyze |
Pipeline | Claude Sonnet 4 | 1m 55s | 10.5 KB, 6 diagrams, 210 citations |
query --deep |
Agent | Claude Sonnet 4 | 2m 31s | 7.5 KB DI deep dive |
review --deep |
Agent | Gemini Flash | 1m 46s | 6.8 KB, 9 review findings |
impact --deep |
Agent | GPT-4.1 | 2m 50s | 12.4 KB impact analysis |
Browse the full examples with generated docs: github.com/ereshzealous/archexa/tree/main/examples/fastapi
Getting Started
Full documentation — installation, config reference, provider setup for every major AI service, all commands, troubleshooting — lives in the repo:
github.com/ereshzealous/archexa
This is a public beta. I'd appreciate any feedback — what works, what doesn't, what you'd want it to do. Issues and stars are both welcome.
License: Apache 2.0
Top comments (0)