AI Engineering · Open Source
Scheme Weaver
Describe a system in plain English — or point it at a git repo — and Scheme Weaver builds a structured model of the architecture, then keeps every diagram derived from it. Diagrams come from data, not from someone dragging boxes around.
Overview
Architecture Diagrams Go Stale. Data Doesn't Have To.
Every team has an architecture diagram that was right once. It was drawn by hand, it lives in a slide deck, and nobody updates it because updating it means redrawing it. Scheme Weaver treats the architecture itself as the artifact: a persistent System with a description, a typed model and any number of views — plus an append-only log of every change.
Generating a diagram from a prompt is the easy part. The interesting part is keeping the description, the model and the pictures consistent as the system evolves.
Model
Three Layers, Each Derived From the One Above
Prose
A short plain-English description of the system — what a person would write in a design doc.
Ontology
Typed entities (services, databases, queues, gateways, teams…) and typed relationships (calls, owns, publishes, stores_in…), grouped by domain.
Views
Named diagrams derived from the ontology, each optionally scoped to a domain, a set of tags or a selection of entities.
Prose ──AI sync──► Ontology ──deterministic──► Views (DIR → SVG)
▲ ▲ │
└─────────AI sync─────┘◄───────────────────────────────┘Rendering
Semantic SVG You Can Round-Trip
The renderer produces SVG that means something: every node, edge and group is a labelled element with a stable ID, a type and an accessible name, validated for accessibility by a small companion library. The DIR that produced the picture is embedded in the SVG's metadata, so an exported diagram carries its own source and can be loaded back into the editor.
<svg role="img" aria-label="Diagram: Payments — Overview">
<metadata><sw:dir>{ …the DIR JSON… }</sw:dir></metadata>
<g id="node-payment-service" class="sw-node"
data-node-type="service" data-technology="fastapi"
aria-label="Payment Service: handles payment processing"> … </g>
</svg>Feature
From a Git Repo to an Architecture Model
Paste a repository URL and Scheme Weaver clones it, reads its manifests, docker-compose files and code, and compiles what it finds into a knowledge base in Markdown. The ontology is derived from that knowledge base — which you can read and edit — rather than from the raw code, so the model's reasoning is inspectable and correctable before it becomes a diagram.
Entities get technology icons from Simple Icons through keyword heuristics and an alias table, and cloud vendors get their own stroke colours, so a diagram reads at a glance.
Editor
A Layout Engine Built From Nine Forces
The web editor lays diagrams out with a multi-objective, force-directed engine. Each objective contributes a weighted force; together they produce layouts that respect domains and flow instead of a generic hairball. Busy diagrams stay readable through edge collapsing: edges fanning into or out of several members of a group fold into one group-level edge, and group-to-group traffic collapses to a single edge with a count badge.
node-repulsion
prevents overlap
edge-attraction
springs toward an ideal edge length
group-cohesion
pulls group members toward their centroid
group-separation
pushes unrelated groups apart
group-alignment
aligns members along the dominant axis
topological-order
encourages edges to flow top to bottom
edge-crossing
approximate crossing penalty
grid-alignment
snaps nodes toward a 40 px grid
boundary
soft wall inside the canvas padding
Decisions
Four Decisions Worth Explaining
The model never draws
Why: Asking an LLM for SVG or Mermaid gives you output that is hard to validate, impossible to diff, and different every time. Claude generates a DIR — a Diagram Intermediate Representation — as JSON checked against a schema. A deterministic renderer turns DIR into SVG, so the same input always produces the same picture.
Trade-off: One more schema to own and version. In return the renderer is unit-testable, and exporters (SVG, PNG, Mermaid) are just functions of the DIR.
The ontology is the source of truth
Why: A diagram is one view of a system; a team needs several. Deriving every view from one ontology keeps them consistent, and deriving the ontology from prose (or prose from the ontology) keeps the description honest as the architecture changes.
Trade-off: Syncing prose and ontology needs the model, and models make mistakes — so every AI sync shows a diff preview before it is applied. Ontology → view is deterministic and needs no model at all.
Composable layout objectives, not a fixed algorithm
Why: Architecture diagrams have structure a generic graph layout ignores: domains should cluster, unrelated groups should separate, requests should flow downward. Each concern is a small force objective with a weight, and custom objectives can be registered at runtime.
Trade-off: More knobs to tune, and the crossing penalty is O(E²). Layout only recomputes when the graph's topology changes, so dragging a node never reshuffles the diagram.
Slow work goes to a worker
Why: Generating a system, or importing a whole repository, can take far longer than a request should. Those jobs run on an ARQ worker backed by Redis, and the FastAPI server stays responsive for the editor.
Trade-off: Redis becomes a dependency for local development; a justfile brings the whole stack up with one command.
In development
Open source, runs locally
The full stack — API, worker, CLI and editor — comes up with a single just dev. Next on the roadmap: scoped views in the editor, a GitHub Action for diagrams-as-code in CI, and a VS Code extension.
Interested in working together?
Get in touch