lookbkdev/blueprint-architecture

Blueprint Architecture Diagramm

Ein System, gezeichnet wie ein technisches Blatt: eine gerasterte Blaupause (oder ein heller „Whiteprint"), jede Komponente als beschriftete Form entsprechend ihrer Art, Pfeile für Requests und gestrichelte Pfeile für Events, gestrichelte Zonen für Gruppen, eine Legende und einen Titelblock. Du (oder die Person) beschreibst das System als diagram.json; ein Skript erstellt das Layout mit dagre (enthalten, nichts zu installieren) und zeichnet:

• out/index.html: das Diagramm mit einem Punkt, der sich entlang jeder Verbindung bewegt, und den fließenden Eventlinien. Öffnet sich von der Festplatte und skaliert mit dem Fenster.
• out/diagram.svg: die gleiche Zeichnung ohne Bewegung – für Dokumentationen, Wikis und Folien.
• out/diagram.png: ein Standbild in doppelter Größe, erstellt mit Headless Chrome – für alles, wo Bilder gebraucht werden.

Was du brauchst

• Node.js 18 oder neuer. Zum Bauen wird nichts weiter benötigt.
• Chrome, Chromium oder Edge für das PNG. Das Skript findet sie an den üblichen Orten; setze CHROME_PATH, falls nicht.
• Internetzugriff beim Öffnen oder Exportieren des Diagramms für die JetBrains Mono Schriftart von Google Fonts (ohne Internetzugriff wird auf die systemeigene Monospace-Schriftart zurückgegriffen).

Der Ordner dieses Skills ist <skill> im Folgenden: der Ordner, in dem diese SKILL.md liegt.

Schritte

1. Das System ermitteln

Wenn die Person das System beschreibt, verwende ihre Worte. Wenn du aufgefordert wirst, ein Repository auszulesen, sammle Belege, bevor du etwas zeichnest, und zeichne nur das, was du gefunden hast:

1. Ausführbare Einheiten: Dienste in docker-compose*.yml, Kubernetes Deployments, Helm-Charts, Procfiles, Serverless-Konfigurationen (serverless.yml, vercel.json, wrangler.toml), Terraform-Ressourcen und Apps in einem Monorepo (apps/, services/, packages/* mit einem Startskript).
2. Datenspeicher und Message Broker: Images und verwaltete Ressourcen (postgres, mysql, mongo, redis, kafka, rabbitmq, sqs, s3) sowie Verbindungseinstellungen wie DATABASE_URL, REDIS_URL, KAFKA_BROKERS, Bucket-Namen.
3. Verbindungen: HTTP-Clients und Base-URLs, die auf andere Dienste verweisen, gRPC-Stubs, Queue-Producer und -Consumer (Topic- und Queue-Namen), depends_on, ausgehende Aufrufe an Dritte (Stripe, eine LLM-API, E-Mail-Anbieter).
4. Aufrufer: Web- und Mobile-Apps, CLIs, Cron-Jobs, Webhooks.

Halte 5 bis 20 Knoten ein. Fasse Replikate und kleine Helfer in den zugehörigen Dienst zusammen; teile lieber auf mehrere Blätter auf ("sheet": "02 / 03"), anstatt alles zu quetschen. Notiere alles, was du eher erschlossen als gefunden hast, und teile es der Person mit.

2. diagram.json schreiben

{
  "title": "Order service · v2",
  "subtitle": "Systemarchitektur · aus /services und docker-compose.yml · 21. Okt. 2026",
  "sheet": "01 / 01",
  "direction": "LR",
  "theme": "blueprint",
  "groups": [{ "id": "core", "label": "Order-Plattform" }],
  "nodes": [
    {
      "id": "gateway",
      "label": "API-Gateway",
      "sub": "auth · Ratenbegrenzung",
      "kind": "service"
    },
    {
      "id": "orders",
      "label": "Order-Service",
      "sub": "v2 · Go · 6 Pods",
      "kind": "service",
      "group": "core",
      "focus": true
    },
    {
      "id": "db",
      "label": "Postgres",
      "sub": "orders · bestand",
      "kind": "database"
    },
    {
      "id": "bus",
      "label": "Event-Bus",
      "sub": "Kafka · 3 Topics",
      "kind": "queue"
    }
  ],
  "edges": [
    { "from": "gateway", "to": "orders", "label": "POST /orders" },
    { "from": "orders", "to": "db", "label": "SQL" },
    { "from": "orders", "to": "bus", "label": "order.created", "async": true }
  ]
}

Feld	Was es ist	Limit
title	Name des Systems oder der Ansicht (erforderlich); kommt auch in den Titelblock	60
subtitle	Was die Zeichnung zeigt und woher sie stammt: Quellen und Datum	100
sheet	Blattnummer im Titelblock, z. B. "02 / 03" (Standard 01 / 01)	–
direction	LR links nach rechts (Standard, geeignet für Requestflüsse) oder TB oben nach unten (Pipelines)	–
theme	blueprint (dunkelblau, Standard), whiteprint (hell) oder Farben: { "paper", "line", "accent", "dim" } als Hex	–
groups	Zonen, die um ihre Knoten gezeichnet werden: { "id", "label" }	–
nodes[].id	Buchstaben, Ziffern, - oder _; Kanten beziehen sich darauf (erforderlich)	–
nodes[].label	Name auf dem Knoten (erforderlich)	28
nodes[].sub	Zweite Zeile: Sprache, Laufzeit, Skalierung, Inhalt	36
nodes[].kind	Form: service (Standard), client, database, queue, cache, storage, function, external (Drittanbieter, gestrichelt)	–
nodes[].group	Eine Gruppen-ID	–
nodes[].focus	true zeichnet es in der Akzentfarbe: das Element, um das es im Diagramm geht	–
edges[]	{ "from", "to" } Knoten-IDs, in Richtung des Daten- oder Steuerflusses	–
edges[].label	Protokoll, Endpunkt, Topic oder Verb: HTTPS, POST /orders, order.created	24
edges[].async	true für Events, Queues und alles, was feuer-und-vergiss ist (gestrichelt, fließend)	–

Tipps:

• Beschrifte Kanten mit dem, was tatsächlich übertragen wird: ein Endpunkt, ein Topic, eine Tabelle, ein Verb. Lass eine Beschriftung nur weg, wenn sie nichts beiträgt.
• Richte Kanten in die Richtung der Requests (Aufrufer zu Aufgerufener) und der Ereignisse (Produzent zu Queue zu Konsument).
• Markiere höchstens einen Knoten als focus.
• Bis zu 40 Knoten sind erlaubt, aber ab etwa 20 wird die Zeichnung schwer lesbar.

3. Bauen und prüfen

node <skill>/scripts/build.mjs diagram.json out

Es prüft die Datei und listet jedes Problem auf einmal auf (eine Kante zu einem nicht existierenden Knoten, eine Beschriftung über dem Limit) und schreibt dann out/index.html und out/diagram.svg. Öffne out/index.html und prüfe:

• jeder Knoten aus Schritt 1 ist vorhanden, und nichts, was du nicht gefunden hast,
• Kanten zeigen in die richtige Richtung und ihre Beschriftungen sind lesbar,
• Gruppen enthalten die richtigen Knoten.

Wenn das Layout verworren ist, versuche die andere direction oder ordne nodes und edges neu: Das Layout beginnt mit ihrer Reihenfolge.

4. PNG exportieren

node <skill>/scripts/export-png.mjs out/index.html

Es schreibt out/diagram.png in doppelter Größe der Zeichnung; füge --scale=1 für die tatsächliche Größe hinzu.

5. Übergeben

Übergebe der Person out/index.html (animiert), out/diagram.svg und out/diagram.png sowie diagram.json, damit die Zeichnung aktualisiert werden kann, wenn sich das System ändert: Bearbeite das JSON und führe die Schritte 3 und 4 erneut aus. Wenn das Diagramm zum Repository gehört, ist ein Ordner docs/architecture/ mit dem JSON und dem SVG ein guter Ort; das SVG wird in GitHub und den meisten Wikis gerendert.

Fehlerbehebung

• build: fix diagram.json first: Jede Zeile benennt den Knoten oder die Kante und was zu ändern ist.
• Der PNG-Schritt meldet, dass kein Chrome gefunden wurde: Setze CHROME_PATH oder öffne out/index.html und erstelle einen Screenshot.
• Text ist in einer anderen Monospace-Schriftart: Die Seite konnte Google Fonts nicht erreichen. Installiere JetBrains Mono (kostenlos) für eine korrekte Darstellung offline.
• Kanten kreuzen sich häufig: Wechsle die direction, verschiebe den verworrenen Knoten in nodes nach vorne oder hinten, oder teile das System auf zwei Blätter auf.

Dateien

• scripts/build.mjs: Prüft diagram.json, erstellt das Layout und zeichnet das HTML und SVG. Keine Abhängigkeiten zu installieren.
• scripts/export-png.mjs: Speichert das PNG mit Headless Chrome.
• vendor/dagre.esm.js: Die dagre-Graphlayout-Bibliothek (MIT), gebündelt, sodass nichts installiert werden muss; ihre Lizenz ist in vendor/LICENSE-dagre.txt.
• examples/order-service/ (Blaupause, links nach rechts) und examples/rag-pipeline/ (Whiteprint, oben nach unten): fertige diagram.json-Dateien. Die Vorschauen auf Lookbk werden daraus erstellt.
• NOTICE.md: Drittsoftware und Schriftarten, die dieser Skill verwendet.