Architecture overview
How the codebase splits into services and modules, what each one owns, and where the boundaries sit.
Architecture documentation
Architecture docs generated from the code that exists today
Architecture diagrams are usually right the week they are drawn. Moxie writes the architecture layer from your repository - how services and modules fit, which flows cross which files - and re-checks it every time the code moves.
Quick Answer: Moxie Docs generates software architecture documentation directly from a connected GitHub repository. It writes an architecture overview of services, modules, and their boundaries, traces cross-file flows such as request paths and job pipelines with Mermaid diagrams, and adds a directory guide, citing the source files behind each claim. Every merge re-checks the pages that cite changed files, so the architecture docs keep matching the code.
- Read from source. Boundaries and flows come from the code, not from memory or a whiteboard photo.
- Diagrams included. Mermaid diagrams for the paths that span files, rendered in the workspace and in Git.
- Kept current. Pages that cite a changed file are re-checked on every merge.
What you get
What the architecture layer covers
Cross-file flows
Request paths, job pipelines, and auth handshakes traced through every file they touch, with a diagram.
Cited to source
Every section links the paths it was written from, so a reviewer can check a claim in one click.
Directory guide
What lives where, so new engineers and agents stop guessing at paths.
Drift on merge
A merged change that alters a documented boundary or flow is flagged against the page that describes it.
Architecture context for agents
Cursor, Claude Code, and Codex read the same architecture pages over MCP before they edit.
How it works
From repository to architecture docs
- 01
Connect GitHub
Install the app on the repositories you want mapped, including private repos and monorepos.
- 02
Plan the outline
Moxie decides which architecture pages the codebase warrants, scaled to the size of each subsystem.
- 03
Write each page
Every page gets its own pass against the files it describes, with diagrams for multi-file flows.
- 04
Keep it true
Merges re-check the touched pages; fixes arrive as reviewable docs-only PRs.
The problem
Why architecture docs are the first to go stale
Architecture documentation describes the parts of a system that change least often, which is exactly why nobody checks it when they do change. The page survives for years, confidently wrong.
01 Drawn once, never redrawn
The diagram came from a planning meeting. Three refactors later it still shows the service that was merged away.
02 Owned by nobody
Feature work has an owner. The system overview belongs to whoever wrote it, who may have left.
03 Invisible in review
A pull request that moves a boundary does not touch the architecture page, so no reviewer sees the mismatch.
04 Agents trust it anyway
A coding agent that reads an outdated overview will put new code where the architecture used to be.
Scope
Where generated architecture docs fit next to ADRs
Generated docs describe what the system is. Architecture decision records explain why it became that way. You want both, and they should not compete.
Moxie writes and maintains the descriptive layer from source: boundaries, flows, and layout. Decisions, trade-offs, and rejected options still come from the people who made them, so keep ADRs in the repository and Moxie indexes them alongside the generated pages. Use the free ADR generator to start one.
- Generated: architecture overview, cross-file flows, directory guide, API surface.
- Human-written: ADRs, RFCs, and design rationale. Indexed and searchable, never overwritten.
- Both: checked for drift on merge against the source paths they cite.
At a glance
Ways teams keep architecture docs
Diagram tools and wikis capture a moment. Coupling the docs to the repository is what keeps them accurate.
Source of truth
Diagramming tool
Whoever drew it
Wiki page
Whoever last edited it
Moxie
The repository, cited per section
Updates when code changes
Diagramming tool
Manually
Wiki page
Manually
Moxie
Re-checked on every merge
Lives next to the code
Diagramming tool
No
Wiki page
No
Moxie
Yes - Markdown and Mermaid in the workspace and repo PRs
Readable by coding agents
Diagramming tool
No
Wiki page
Copy and paste
Moxie
Served over MCP
| Diagramming tool | Wiki page | Moxie | |
|---|---|---|---|
| Source of truth | Whoever drew it | Whoever last edited it | The repository, cited per section |
| Updates when code changes | Manually | Manually | Re-checked on every merge |
| Lives next to the code | No | No | Yes - Markdown and Mermaid in the workspace and repo PRs |
| Readable by coding agents | No | Copy and paste | Served over MCP |
FAQ
Frequently asked questions
Get started
See your architecture as the code describes it
Connect a repository and the first index writes the architecture overview, flows, and directory guide. Free on one repo, no card required.