ai-architecture-renderer

Generate SVG perspectives of a multi-service system from a registry of TOML config files + filesystem walks. Diagrams that can't drift — they're projections of the source of truth.

Lifted from raj-sadan, where it was built because PM said "I trust your judgment but have no visual way to verify what you're building." If you have that problem with your own multi-service system, this tool may help.

Status: v0.1.0. Three perspectives shipped (service-mesh, neural-organs, constitutional). Generic registry schema; raj-sadan-shaped systems supported out of the box.

What it does

Reads structured config (TOML) + walks the filesystem; renders three SVG perspectives plus a manifest.json with timestamps and counts:

Output is plain SVG. Embed in your dashboard, paste into a doc, host on the static directory of your service. Re-run when the source of truth changes.

Install

# 1. Install Graphviz (the binary, not the Python wrapper)
sudo apt-get install graphviz       # Linux
brew install graphviz                # macOS
winget install graphviz              # Windows

# 2. Install the package
pip install ai-architecture-renderer

Use

Against your own repo

ai-architecture-renderer --root /path/to/repo --output diagrams/

The default --root is the current working directory; --output defaults to <root>/architecture.

Single perspective

ai-architecture-renderer --root . --perspective service-mesh
ai-architecture-renderer --root . --perspective neural-organs
ai-architecture-renderer --root . --perspective constitutional

Sample registries

The examples/ directory has three sample shapes:

• raj-sadan/ — full nervous-system stack (5 organs + ministers + sherpas + protocols). The reference implementation.
• simple-three-tier/registry.toml — classic web → api → db. Smallest possible example.
• microservices/registry.toml — six services + gateway + queue + db.

Try them with:

git clone https://github.com/vraj0703/ai-architecture-renderer
cd ai-architecture-renderer
ai-architecture-renderer --root examples/simple-three-tier

What it expects to find

The renderer reads from a few raj-sadan-style paths by default:

• mind/cortex/config.toml — service registry
• senses/interoception/state/registry.toml — operational state
• CONSTITUTION.toml — articles + ministers + sherpas
• protocols/PROTOCOL-*.toml — protocol files
• .claude/skills/ministry-*/ — minister directories
• mind/sherpa/*/ — sherpa directories

If your repo has these (or you symlink to them), it works out of the box. If not, the missing perspective panels fall back to "(no data)" labels — partial diagrams still render.

What's not yet here: a fully generic registry schema where every source path is configurable per-perspective via a single registry.toml. Today it's "raj-sadan-shaped + missing-data-tolerant." A v0.2 plan to fully decouple the source paths is tracked.

Why this exists

Most architecture diagrams drift the moment they're drawn. Lucidchart files diverge from reality the day after the last refactor. Mermaid blocks in READMEs go stale. The fix isn't a better drawing tool — it's making the diagram a projection of the source of truth, regenerable any time, never authoritative on its own.

That's all this is. A small Python script that reads what's actually there + renders SVG. Re-run it when you change something and the diagram updates. Don't, and the diagram stays correct because nothing in the system has moved.

Configuration

Both can also be passed as --root / --output CLI flags, which take precedence.

License

MIT.

See also

• The original raj-sadan tools/architecture/render.py (this tool's source)
• ai-mind, ai-senses, ai-memory, ai-knowledge — the organs the neural-organs perspective is built around
• ai-constitution — the governance framework the constitutional perspective expects