arch-wiki 🏛️

Framework-agnostic architecture documentation skill — Automatically sync your API modules, endpoints, Docker topology, SQL queries, permissions, and Swagger spec into a beautiful interactive HTML dashboard.

---

What is arch-wiki?

Turn any backend codebase into an interactive architecture wiki that both developers and AI coding assistants can use.

arch-wiki is an AI skill (agent instruction set) that keeps your living architecture documentation in perfect sync with your codebase. Every time you add a module, endpoint, permission, SQL query, or Docker service — you invoke the skill, and it:

1. Reads your architecture.json manifest
2. Scans the changed source files
3. Updates the JSON manifest with new entries
4. Regenerates a fully interactive HTML dashboard

The output is a single self-contained HTML file with:

• 📊 Overview stats dashboard
• 📋 System Prerequisites & Setup Pipeline
• 📦 API Modules catalog with all endpoints & 1-click AI Analysis Prompts
• 🤖 Interactive Senior Developer Analysis Prompts modal for every API endpoint
• 🏗️ System Architecture diagram with pan/zoom & hand cursor (Mermaid)
• 🐋 Docker Topology diagram with pan/zoom & hand cursor (Mermaid)
• 📄 One-click PDF Export (exports all 11 sections into a single formatted PDF document)
• ⚡ Interactive Swagger UI (try-it-out enabled with polished dark mode theme)
• 🔐 Permissions & RBAC mapping
• 🗃️ SQL Queries catalog with syntax highlighting
• 🖥️ Infrastructure services catalog
• 🛡️ Core Layer & Request Pipeline docs

---

🤖 AI Token & Context Optimization

Beyond serving as an interactive dashboard, architecture.json acts as a machine-readable context index specifically designed for AI coding assistants (Antigravity, Claude Code, Cursor, Codex, OpenCode, etc.):

• ⚡ Fast Code Reading: AI tools can read docs/architecture/architecture.json in a single file view to immediately understand all API modules, endpoints, database queries, RBAC permissions, and container topologies.
• 🪙 Massive Token Savings: Eliminates the need for AI agents to make dozens of grep or file-reading calls across hundreds of source files, saving thousands of prompt tokens and drastically lowering API context consumption.
• 🎯 Pinpoint Navigation: Every endpoint and SQL query in architecture.json links directly to its underlying file path (controller.ts, router.py, repository.ts), allowing AI agents to navigate straight to relevant files without scanning the entire repo.
• 🧠 Living System Blueprint: Gives AI models a structured, top-down mental model of your architecture that persists across chat sessions.

---

Project Structure

arch-wiki/
├── SKILL.md              ← AI skill definition
├── README.md             ← This file
└── templates/
    └── build_html.py       ← HTML dashboard generator + architecture.json initialiser (~83 KB)

architecture.json is automatically generated on first run by build_html.py --init via a zero-dependency codebase scanner. It automatically scans your docker-compose.yml, route files (*.routes.ts, routers/*.py), and package.json to populate endpoints, services, workspaces, permissions, prerequisites, and SQL queries without manual setup! Built-in deduplication automatically filters out build directories (dist/, build/, node_modules/) to prevent duplicate route definitions.

In your target project, the architecture setup is simple:

your-project/
└── docs/
    └── architecture/
        ├── architecture.json   ← Generated on first run (AI keeps updated)
        ├── build_html.py       ← Generator (copied from arch-wiki/templates/)
        └── architecture.html   ← Generated output (never edit manually)

---

Quick Start (Installation & Setup)

Option A: Install via npx

1. From Git Repository (Hosted on GitHub/GitLab)

npx github:your-username/arch-wiki

2. From Local Directory (Local Development without publishing)

# Point npx to your local folder:
npx ./path/to/arch-wiki

# OR run the installer directly with node:
node ./path/to/arch-wiki/bin/install.js

# OR use npm link for a global 'arch-wiki' command:
cd path/to/arch-wiki && npm link

3. From NPM Registry (Once published)

npx arch-wiki

This automatically registers the arch-wiki skill into your AI assistant environment (Antigravity, Claude Code, Cursor, etc.).

---

Option B: Manual File Copy

Copy SKILL.md into your AI tool’s skills folder:

# Antigravity AI Agent
mkdir -p ~/.gemini/antigravity/skills/arch-wiki
cp SKILL.md ~/.gemini/antigravity/skills/arch-wiki/SKILL.md

# Claude Code
mkdir -p ~/.claude/skills/arch-wiki
cp SKILL.md ~/.claude/skills/arch-wiki/SKILL.md

---

How to Use

Once installed, you never need to run python scripts manually. Simply open your AI coding assistant and ask:

💬 “Run the arch-wiki skill on this project”

The AI Assistant will autonomously:

1. Copy the codebase scanner engine into docs/architecture/build_html.py.
2. Scan Docker services (docker-compose.yml), API endpoints (*.routes.ts, routers/*.py), permissions, prerequisites, and SQL queries.
3. Create/Sync docs/architecture/architecture.json.
4. Generate the interactive dashboard at docs/architecture/architecture.html.

---

Setup Guides

Setup in Antigravity

Copy SKILL.md into your Antigravity skills directory:

# Option A: Copy as a named skill
cp arch-wiki/SKILL.md ~/.gemini/antigravity/skills/arch-wiki/SKILL.md

# Option B: Use directly from any project folder
# Just ensure the AI can access this SKILL.md file

Then invoke it by referencing the skill in your prompt:

Use the arch-wiki skill. I just added a new [module/endpoint/service].

---

Setup in Claude Code / Cursor

Add SKILL.md to your project as a context file. You can either:

Option A: Add to .claude/ directory (Claude Code)

mkdir -p your-project/.claude
cp arch-wiki/SKILL.md your-project/.claude/arch-wiki.md

Option B: Add to .cursor/rules/ (Cursor)

mkdir -p your-project/.cursor/rules
cp arch-wiki/SKILL.md your-project/.cursor/rules/arch-wiki.md

Then prompt your AI:

Follow the instructions in .claude/arch-wiki.md / .cursor/rules/arch-wiki.md.
I just added a new module called [X].

---

Setup in OpenAI Codex

Add the skill as a system instruction or paste it into the Codex context window:

# Print the skill content to paste into Codex
cat arch-wiki/SKILL.md

Or reference it as a file in your project and tell Codex:

Read and follow the instructions in arch-wiki/SKILL.md to update
my architecture documentation.

---

Setup in OpenCode

Add SKILL.md to your OpenCode project context:

cp arch-wiki/SKILL.md your-project/arch-wiki.md

Then in your OpenCode session:

Read arch-wiki.md and follow its instructions to update docs/architecture/
after my recent changes to [module/service/endpoint].

---

Setup for Any Other AI Tool

The skill is a plain Markdown file. Any AI assistant that can:

• Read files (view_file / read_file)
• Edit JSON files
• Execute shell commands (python docs/architecture/build_html.py)

…can use this skill. Simply provide the contents of SKILL.md as the system/context instruction.

---

Simple Usage Examples

Because arch-wiki has a zero-dependency codebase scanner, you don’t need to write long prompts or manually list your endpoints. Just tell your AI:

Initial Setup

💬 “Run @arch-wiki to generate architecture documentation for this project.”

After Codebase Changes

💬 “Run @arch-wiki to sync my architecture documentation with recent changes.”

The AI assistant will automatically run the codebase scanner, detect any new or updated endpoints, permissions, SQL queries, or Docker containers, and re-render architecture.html.

🤖 Interactive Senior Developer Endpoint Analysis Prompts

Clicking on any API endpoint in the API Modules view (or using its 📋 Prompt button) opens an interactive modal with a tailor-made Senior Developer Analysis Prompt.

The prompt is dynamically formatted for the selected endpoint (e.g. POST /api/v1/orders), instructing an AI coding assistant to:

1. Act as a senior developer joining the project.
2. Analyze the endpoint using architecture.json, arch-wiki documentation, and project source code.
3. Discover the actual implementation flow and generate accurate Mermaid sequence and flowchart diagrams.
4. Adhere to strict boundaries (only include components and interactions that actually exist in code, do not infer missing components, do not modify code).

Includes a 1-click 📋 Copy to Clipboard button directly on every endpoint card and inside the modal for instant integration with AI assistants.

---

architecture.json Schema Reference

---

Framework Compatibility

The skill is designed to work with any backend framework. The AI adapts the source file scanning paths based on your stack:

---

Dashboard Screenshots

The generated architecture.html includes 11 navigation sections:

---

Benchmark

The benchmark compares the same software understanding tasks using two approaches:

1. Direct AI exploration of the repository.
2. AI using arch-wiki and architecture.json.

The goal is not to measure token consumption only. The main goal is to evaluate whether arch-wiki can reduce repository exploration while producing a more accurate and useful architecture understanding.

1. Benchmark Prompts

2. Results

3. Opinion

4. Initial Benchmark Conclusion

The most interesting result is not simply that arch-wiki makes the AI faster.

The important observation is:

The AI can use a pre-generated architecture representation as a map of the system instead of rediscovering the architecture from scratch for every question.

In the tested scenarios, arch-wiki significantly reduced repository exploration, especially for high-level architecture and change-impact questions.

The benchmark also exposed an important limitation:

Architecture documentation must be accurate. If architecture.json contains incorrect or inferred information, the AI can propagate those mistakes instead of discovering the truth directly from the source code.

Therefore, the next step is to measure accuracy, not just exploration reduction.

Requirements

• Python 3.8+ (only standard library — json, re, os, sys, datetime — no pip install needed)
• Any AI assistant that can read/write files and run shell commands
• Docker is optional — if dockerDiagram.nodes is empty, the Docker tab shows a friendly placeholder

---

License

MIT — Use freely in any project.

---

Contributing

To extend or adapt this skill:

1. Edit SKILL.md to add new sections or update instructions
2. Edit templates/build_html.py to add new dashboard sections
3. Update templates/architecture.json with new schema fields
4. Update this README.md

---

Built with ❤️ for developers who want their architecture docs to stay alive.