PaintForge

16 diagram types, deterministic layout, verifiable output. A skill that turns plain-language requirements (or Mermaid) into polished, self-contained HTML diagrams — with SVG, dark/light themes, pan/zoom, search, and export to PNG / JPEG / WebP / SVG / WebM.

Forked from tt-a1i/archify (MIT), rebranded and expanded by AnyForge.

---

Install

Global install (recommended)

npx skills add anyforge/PaintForge -g

Installs to the user level — available in every project and session.

Project install

npx skills add anyforge/PaintForge

Installs to the current project only.

Install everything (all skills, all agents, no prompt)

npx skills add anyforge/PaintForge --all

The skill runs with zero runtime dependencies (validators are precompiled and inlined). Requires Node.js ≥ 18.

Verify the install:

node paintforge/bin/paintforge.mjs doctor

---

Use it — describe your idea in plain language

After installing, send your agent something like this:

Use PaintForge to draw the user signup flow:
enter email → validate → create account → send welcome email.
Make validation a decision diamond with a "fix errors" loop back.

Use PaintForge to model the order database:
Customer, Order, OrderItem, Product, Payment —
mark primary keys, foreign keys, and one-to-many cardinality.

Use PaintForge to map this team's reporting structure,
and a Gantt chart of the release plan for next quarter.

Then keep refining in chat: "add a Payment entity", "highlight the cache-miss path", "switch to the light theme", "export a PNG".

No repository is required — start from a description, or ask your agent to read a repository for a source-backed architecture diagram.

---

Why PaintForge?

Most diagram tools hand you pixels or syntax. PaintForge hands you a verifiable artifact.

vs archify

PaintForge is a fork of archify, which pioneered the deterministic-layout + verifiable-output engine. We keep that engine and build on it:

	archify	PaintForge
Diagram types	5	16
Deterministic layout	✅	✅ (inherited)
Byte-level receipt (deliver)	✅	✅ (inherited)
Real-browser verification	✅	✅ (inherited)
ER / dependency / org / mindmap	❌	✅
Flowchart / network / matrix / kanban / venn / gantt / sankey	❌	✅
Update checker	✅	removed (manual updates)
Install	npx skills add tt-a1i/archify	npx skills add anyforge/PaintForge -g

The original 5 types are unchanged — all the inherited guarantees still hold. PaintForge adds 11 new diagram types on the same verifiable foundation.

vs everyone else

	Mermaid / PlantUML	ECharts / D3	PaintForge
Deterministic output	⚠️ renderer-dependent	❌ runtime-rendered	✅ byte-stable SVG
Byte-level receipt (SHA-256)	❌	❌	✅deliver
Real-browser verification	❌	❌	✅visual-check
Anti-hallucination guards	❌	❌	✅ built into the contract
Self-contained HTML	⚠️ needs CDN/CLI	❌ needs a JS lib	✅ zero-dependency
Types covered	~6	statistical charts	16

The loop is strict on purpose: validate (schema + geometry) → deliver (freeze bytes + SHA-256) → visual-check (real Chrome evidence). A non-zero exit can never be described as success — the skill refuses to fake a pass.

---

Choose the right diagram

Type	Best for	Include in your prompt
architecture	components, services, boundaries	scope, core components, primary path
workflow	approvals, CI/CD, runbooks	participants, order, branches, exceptions
sequence	API chains, cache fallback, auth	callers, callees, returns, timing
dataflow	pipelines, lineage, PII	sources, transforms, stores, boundaries
lifecycle	states, retries, terminals	states, events, retry/cancel paths
er	database schema, keys	entities, attributes, PK/FK, cardinality
dependency	module/package graphs	modules, versions, runtime vs dev
org	reporting hierarchy	people, titles, who reports to whom
mindmap	brainstorming, outlines	central topic, main branches
flowchart	process, decision trees	steps, decisions, yes/no branches
network	topology, devices	device kinds, physical/logical links
matrix	2×2 priority, value vs effort	two axes, item scores
kanban	task board, sprint status	columns, cards, priorities
venn	set overlap, shared ownership	2-3 sets, intersections
gantt	timeline, schedule	tasks, start/end dates
sankey	flow quantities	stages, flows with values

Not sure which fits? Ask the zero-dependency CLI:

node paintforge/bin/paintforge.mjs guide "Show an API request with a Redis cache miss"
node paintforge/bin/paintforge.mjs guide "Map the order database schema" --json

---

How it works

Step	What happens
Generate	The agent creates typed JSON IR from your description.
Validate	Bundled validators and layout rules check the source; failures name the exact repair in machine-readable JSON.
Deliver	A same-directory candidate is rendered and checked; only a passing artifact atomically replaces the target, with a SHA-256 receipt.
Verify	visual-check loads the delivered HTML in a real browser and reports containment + readability evidence.
Iterate	The agent updates the source while unrelated structure stays stable.

On failure, validate --json and deliver --json emit one JSON object with rule codes, the exact subject, and only supported repair controls. A non-zero exit is never success.

---

The 16 types

Type	For
architecture	components, services, boundaries, infrastructure
workflow	processes, approvals, CI/CD, runbooks
sequence	API chains, request lifecycles, async traces
dataflow	pipelines, ETL, lineage, consumers
lifecycle	states, transitions, retries, terminals
er	entity-relationship, schemas, keys, cardinality
dependency	module/package graphs, runtime vs dev
org	org charts, reporting hierarchies
mindmap	brainstorming, outlines, knowledge maps
flowchart	process flows, decision trees, algorithms
network	topology, devices, links (force-directed)
matrix	2×2 priorities, value-vs-effort
kanban	task boards, sprint status
venn	set overlap, shared responsibility
gantt	timelines, schedules, task bars
sankey	flow quantities across stages

---

Quick start

# Validate an example
node paintforge/bin/paintforge.mjs validate er paintforge/examples/order-system.er.json --quality showcase --json

# Render to HTML
node paintforge/bin/paintforge.mjs render er paintforge/examples/order-system.er.json out.html

# Deliver with a SHA-256 receipt (final acceptance)
node paintforge/bin/paintforge.mjs deliver er paintforge/examples/order-system.er.json out.html --json

# Verify in a real browser
node paintforge/bin/paintforge.mjs visual-check out.html --json

See the demo/ directory for rendered examples of all 16 types.

---

Demo

Rendered samples live in demo/. Open any .html in a browser — each is fully interactive (theme switch, pan/zoom, search, focus, export).

---

License

MIT. See LICENSE. PaintForge is a derivative of tt-a1i/archify (MIT), which itself derives from Cocoon-AI/architecture-diagram-generator (MIT).