Metadata-Version: 2.4
Name: ai-architecture-renderer
Version: 0.1.1
Summary: Generate SVG perspectives of a multi-service system from a registry of TOML config files + filesystem walks. No drift — diagrams are projections of the source of truth.
Author: Vishal Raj
License: MIT
Project-URL: Homepage, https://github.com/vraj0703/ai-architecture-renderer
Project-URL: Repository, https://github.com/vraj0703/ai-architecture-renderer
Project-URL: Issues, https://linear.app/raj-sadan/project/ai-architecture-renderer-extract-diagram-tool-9a4eaa4d57d8
Keywords: architecture,diagrams,svg,registry,ai-agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: diagrams>=0.23
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Dynamic: license-file

# 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.

[![CI](https://github.com/vraj0703/ai-architecture-renderer/actions/workflows/ci.yml/badge.svg)](https://github.com/vraj0703/ai-architecture-renderer/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python: 3.10+](https://img.shields.io/badge/Python-3.10+-blue.svg)](pyproject.toml)

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:

| Perspective | What it shows |
|---|---|
| **service-mesh** | Operational view — running services, their connections, ports |
| **neural-organs** | For agent stacks: organs (mind, senses, memory, knowledge, dashboard) + their internal subdirs and file counts |
| **constitutional** | Governance view — articles, ministers, sherpas, chain of authority |

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

```bash
# 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

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

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

### Single perspective

```bash
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:

```bash
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

| Var | Default | Purpose |
|---|---|---|
| `ARCH_RENDERER_ROOT` | cwd | Repository root to introspect |
| `ARCH_RENDERER_OUTPUT` | `<root>/architecture` | Output directory |

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](https://github.com/vraj0703/ai-mind), [ai-senses](https://github.com/vraj0703/ai-senses), [ai-memory](https://github.com/vraj0703/ai-memory), [ai-knowledge](https://github.com/vraj0703/ai-knowledge) — the organs the `neural-organs` perspective is built around
- [ai-constitution](https://github.com/vraj0703/ai-constitution) — the governance framework the `constitutional` perspective expects
