Zum Hauptinhalt springen

TOGETHER CCA Diagram Style Guide

🤖 Generated with Claude Code

⚠️ Not yet reviewed

Co-Authored-By: Claude (noreply@anthropic.com)

Richtlinien fĂĽr technische Diagramme in TOGETHER CCA Projekten.

Referenzen:

  • Farbpalette: ../../assets/colors/
  • D2 Variablen: ../../assets/colors/_colors.d2
  • User-Icon: ../../assets/icons/user.svg
  • Templates: ./templates/
  • AI Quick Reference: ../AI_QUICK_REFERENCE.md
  • Cookbook: ../cookbook/

0. Grundprinzipien​

Simplicity First​

  1. Monochrom starten. Farbe SOLLTE nur hinzugefĂĽgt werden, wenn sie eine Frage des Lesers beantwortet.
  2. Einfachheit zuerst. Mehrere fokussierte Diagramme SOLLTEN einem komplexen vorgezogen werden.
  3. Barrierefreiheit. Ein Diagramm DARF NICHT allein auf Farbe setzen - Farbe MUSS mit Linienstärke, Strichelung oder Labels kombiniert werden.

1. Tool-Auswahl​

ToolVerwendungOutput
D2Alle Diagramm-Typen (Architecture, Sequence, State Machines, Flowcharts)PNG (Azure DevOps), SVG (optional)
MermaidNur in Ausnahmefällen, wenn bevorzugtInline-Rendering
VisioLegacy, komplexe manuelle LayoutsPDF-Export erforderlich

Standard: D2. AI-Agenten MUESSEN ausschliesslich D2 verwenden.


2. Diagramm-Typen​

2.1 Architecture Diagrams​

Zweck: System-Kontext, Komponenten-Ăśbersicht, DatenflĂĽsse.

direction: right

# Nesting fĂĽr logische Gruppierung
system: "System Name" {
style.fill: ${together-light}

component: Component {
shape: rectangle
}
}

Patterns:

  • direction: right fĂĽr DatenflĂĽsse
  • Container mit style.fill fĂĽr Gruppierung
  • shape: hexagon fĂĽr Gateways/APIs

2.2 State Machines​

Zweck: Status-Lifecycle, Workflow-Zustände.

direction: right

# Terminal States: doppelter Rahmen
completed: Completed {
style.fill: ${success}
style.stroke: ${success-dark}
style.stroke-width: 2
}

# Bedingte Transitions: dashed
state -> next: "Condition" {
style.stroke-dash: 3
}

Patterns:

  • Enum-Werte im Label: Staged (0)
  • Terminal States mit stroke-width: 2
  • Dashed Lines fĂĽr bedingte/System-Transitions

2.3 Flowcharts​

Zweck: Prozesse, Entscheidungslogik.

direction: down

start: Start { shape: oval }
decision: Entscheidung? { shape: diamond }
end: Ende { shape: oval }

start -> decision
decision -> end: Ja

Patterns:

  • direction: down fĂĽr ProzessflĂĽsse
  • shape: diamond fĂĽr Entscheidungen
  • shape: oval fĂĽr Start/End

2.4 Network Diagrams​

Zweck: Infrastruktur, Netzwerk-Topologie.

direction: right

zone: "Zone Name" {
style.fill: ${background}

server: Server {
shape: rectangle
icon: https://icons.terrastruct.com/azure/Compute/10021-icon-service-Virtual-Machine.svg
}
}

Patterns:

  • Zonen als Container
  • Icons fĂĽr Infrastruktur-Komponenten (optional)

2.5 Sequence Diagrams​

Zweck: API-Interaktionen, Request/Response-Flows.

shape: sequence_diagram

client: "Client"
api: "API" {
style.fill: ${together}
}
db: "DB" {
shape: cylinder
}

client -> api: "POST /resource"
api -> db: "INSERT"
db -> api: "OK"
api -> client: "201 Created"

Patterns:

  • shape: sequence_diagram am Anfang
  • System-Farben fĂĽr Participants (Context-Modus)
  • Kurze Participant-Namen
  • Self-calls: a -> a: "Processing"
  • Optional/bedingt: style.stroke-dash: 3

3. Visuelle Standards​

3.1 Farb-Modi (MUSS)​

Farben MUESSEN nach dem Zweck des Diagramms gewählt werden, nicht nach Diagramm-Typ:

ModusZweckKnotenfarbenKantenfarben
ContextWer gehört zu wem?System-Zugehörigkeit (MUSS)System-Herkunft
InternalWie funktioniert es intern?Theme-HierarchieDatenfluss
AnalysisProbleme hervorhebenContainer-GruppenStatus (gut/schlecht)

Internal Mode: Theme-Hierarchie statt System-Farben​

Wenn ein Diagramm nur ein System zeigt (z.B. BOA-API intern), wird bei System-Farben alles gleich eingefärbt → keine visuelle Hierarchie.

FĂĽr Internal Mode gilt:

  • Explizite Container-Fills SOLLTEN NICHT gesetzt werden → das Theme ĂĽbernimmt die Hierarchie
  • Semantische Farben SOLLTEN nur bei System-Affinität verwendet werden (z.B. SoaGfx → CCA-blau, VU-Adapter → VU-grĂĽn)
  • Theme 1 (Neutral Grey) oder ein Custom Theme SOLLTE verwendet werden
# Falsch: Alles orange weil "ist ja TOGETHER"
feature: {
style.fill: ${together-light}
component: { style.fill: ${together} }
}

# Richtig: Theme macht Hierarchie, Farbe nur wo relevant
feature: {
# kein fill
soagfx: { style.fill: ${cca} } # CCA-Affinität
vu_adapter: { style.fill: ${vu} } # VU-Affinität
}

3.2 Farbpaletten​

Modus-spezifische Paletten​

PaletteModusImport
_colors-context.d2ContextSystem-Farben + Alt-Varianten
_colors-internal.d2InternalHierarchie-Ramps + System-Farben
_colors-analysis.d2AnalysisStatus-Farben + System-Alt
_colors.d2AlleVollständige Palette

Setup: In diesem Repository wird die Palette relativ importiert, nicht kopiert — die Anzahl der ../ richtet sich nach der Tiefe des Diagramms, z. B. aus products/shared/identity/diagrams/:

...@../../../../assets/colors/_colors-internal.d2   # modusspezifisch
...@../../../../assets/colors/_colors.d2 # vollständige Palette

In einem anderen Repository wird die passende Datei aus assets/colors/ neben die .d2-Quellen kopiert.

Hierarchie-Ramps (Internal Mode)​

Für Container-Nesting in Internal Mode. Eine Ramp pro Diagramm wählen:

RampFarbenEmpfohlen fĂĽr
slate-1..4Grau (neutral)Default, alle HintergrĂĽnde
sand-1..4Braun (warm)CCA-Hintergrund
lavender-1..4LilaAlle HintergrĂĽnde âś“
teal-1..4BlaugrĂĽnTOGETHER-Hintergrund
turquoise-1..4CyanTOGETHER-Hintergrund
fandango-1..4Rose/PinkAlle HintergrĂĽnde âś“

Kombinationen mit System-Hintergrund:

System-HintergrundBeste RampsVermeiden
TOGETHER (orange)Slate, Lavender, Teal, Turquoise, FandangoSand (ähnlich warm)
CCA (blau)Sand, Lavender, FandangoTurquoise, Slate (ähnlich blau)
...@_colors-internal.d2

# Hierarchie mit Lavender-Ramp
outer: { style.fill: ${lavender-1} }
middle: { style.fill: ${lavender-2} }
inner: { style.fill: ${lavender-3} }
leaf: { style.fill: ${lavender-4} }

Alt-Farben (Konflikt-Vermeidung)​

Jede System-Farbe hat eine Alternative für Fälle wo die Primär-Farbe mit Status-Farben kollidiert:

SystemPrimärAltKonflikt mit
Together${together}${together-alt}warning (orange)
CCA${cca}${cca-alt}info (blau)
VU${vu}${vu-alt}success (grĂĽn)
Kundensystem${kundensystem}${kundensystem-alt}-

System-Farben (Context-Modus)​

Farben importieren​
# Vollständige Palette
...@../../../assets/colors/_colors.d2

# Oder modus-spezifisch
...@../../../assets/colors/_colors-context.d2
...@../../../assets/colors/_colors-internal.d2
...@../../../assets/colors/_colors-analysis.d2
Farbkategorien​
KategorieVariableVerwendung
Kundensysteme${kundensystem}DMS, CRM, externe Partner (lila)
VU-Systeme${vu}, ${vu-dark}Versicherungs-Systeme (grĂĽn)
CCA${cca}, ${cca-dark}CCA Produkte (blau)
TOGETHER${together}, ${together-dark}TOGETHER Platform (orange)
Infrastruktur${neutral}Server, Netzwerk (grau)

Varianten:

  • -light Suffix: Container-Hintergrund (z.B. ${vu-light})
  • -dark Suffix: Rahmen, Betonung (z.B. ${vu-dark})
  • Basis: Komponenten-FĂĽllung (z.B. ${vu})

Status-Farben (Analysis-Modus)​

KategorieHellStandardDunkelVerwendung
Rot${error}-${error-dark}Problematisch, blockierend
Gelb${warning-light}${warning}${warning-dark}Untersuchen, unsicher
GrĂĽn${success}-${success-dark}OK, verifiziert
Grau${neutral-light}${neutral}${neutral-dark}Neutral, unverändert

Einfach halten: Wenn gut/schlecht reicht, nur grĂĽn/rot verwenden.

3.3 Barrierefreiheit (MUSS)​

Rot-Grün-Blindheit ist häufig. Farbe MUSS mit mindestens einem weiteren Hinweis kombiniert werden:

Visueller HinweisVerwendung
LinienstärkeBetonung (dick = wichtig)
StrichelungSicherheit (gestrichelt = unsicher/optional)
LabelsExplizite Bedeutung ("problematisch", "OK")
# Gut: Farbe + Stärke + Label
a -> b: "Problematische Kopplung" {
style.stroke: "#E54040"
style.stroke-width: 3
}

Bei Status-Farben MUSS eine Legende eingefĂĽgt werden.

3.4 Container-Farben (Internal/Analysis-Modus)​

Farb-Hierarchie für Interna​

  1. Produkt-Farbe (wenn vorhanden) → z.B. BOAbot #F49819, OMDSmanager #0066B2
  2. System-Farbe (Standard) → z.B. ${together} für TOGETHER-Interna
  3. Fokus-Farbe (optional) → Komponenten KOENNEN die Farbe des Zielsystems verwenden

Fokus-Farbe: Innerhalb eines Systems kann eine Komponente die Farbe des Systems verwenden, mit dem sie primär interagiert. Z.B. ein VU-Adapter in einem TOGETHER-Service in ${vu} (grün) statt orange - um den Zweck zu verdeutlichen.

Beispiel: Internal Mode mit Fokus-Farben​

...@_colors.d2

boa: "BOA-API" {
style.fill: ${together-light}

controller: "KfzController" {
style.fill: ${together} # System-Farbe
}

# Fokus-Farbe: VU-Adapter in grĂĽn (Zielsystem)
dispatcher: "VU-Dispatcher" {
style.fill: ${vu}
}
}

Container-Pattern​

Jede logische Gruppe bekommt eine Basisfarbe; Elemente darin heller/dunkler:

feature: "Vergleichsrechner" {
style.fill: "#e3f2fd" # heller Container

service: "KfzController" {
style.fill: "#90caf9" # dunklere Komponente
}
}

Kollisions-Warnung: Bei Status-Farben auf Kanten (rot/grĂĽn) diese nicht fĂĽr Container verwenden.

3.5 Projekt-spezifische Farben​

FĂĽr konsistente Komponenten-Farben ĂĽber mehrere Diagramme:

  1. docs/.branding/_project-colors.d2 anlegen
  2. Projekt-Komponenten definieren
  3. In Diagrammen importieren
# docs/.branding/_project-colors.d2
vars: {
soa-gfx: "#90caf9"
identity-server: "#ffcc80"
}

Siehe Cookbook: discover-branding fĂĽr Details.

3.6 Shape-Semantik​

ShapeD2Bedeutung
RechteckrectangleService, Prozess, State
ZylindercylinderDatenspeicher, Queue
HexagonhexagonGateway, API-Endpoint (nur kurze Labels!)
RautediamondEntscheidung
User-Iconicon: ./user.svgBenutzer, Akteur (siehe 3.6.2)
OvalovalStart/End, Event
StepstepProzessschritt
CloudcloudExterne Services

3.6.1 Hexagon-Größe bei APIs​

Hexagons skalieren mit Inhalt und werden bei Listen/mehrzeiligem Text sehr gross.

InhaltEmpfehlung
Kurzes Label ("API Gateway")hexagon âś“
Endpoint-Listerectangle oder separate Nodes
# Falsch: Hexagon mit Liste wird riesig
api: "Public API" {
shape: hexagon
# POST /comparisons
# POST /offers
# ...
}

# Richtig: Hexagon als Label, Endpoints separat
api: "Public API" { shape: hexagon }
endpoints: {
post_compare: "POST /comparisons"
post_offers: "POST /offers"
}
api -> endpoints

3.6.2 User-Icon für Akteure​

FĂĽr Benutzer/Akteure das eigene user.svg Icon verwenden statt shape: person:

# Richtig: Eigenes User-Icon (shape: image fĂĽr rahmenlose Darstellung)
Makler: "Makler/Vermittler" {
shape: image
icon: ./user.svg
}

# Falsch: D2 person shape (nicht verwenden)
Makler: "Makler/Vermittler" {
shape: person
}

Hinweis: Das user.svg liegt in diesem Repository unter assets/icons/user.svg und wird — wie die Palette — relativ referenziert. Siehe Icons für Details.

3.7 Kontrast-Regeln​

# Dunkle Farben (Stufe 7+) → weisse Schrift
dark: {
style.fill: ${cca-dark}
style.font-color: white
}

# Helle Farben (Stufe 0-4) → keine Angabe
light: {
style.fill: ${together}
}

3.8 Connections​

StilD2Bedeutung
Solid(default)Direkter Fluss, Hauptpfad
Dashedstyle.stroke-dash: 3Optional, bedingt, System-gesteuert
Coloredstyle.stroke: ${success-dark}Status-abhängige Transition

4. Naming Conventions​

4.1 Dateinamen (MUSS)​

Ein Dateiname MUSS dem Pattern {domain}-{type}.d2 folgen:

provision-request-state-machine.d2
staging-overview.d2
benutzer-flow.d2

4.2 Element-IDs (MUSS / SOLLTE)​

  • Container MUESSEN kebab-case verwenden: staging-layer, external-sources
  • IDs SOLLTEN kurz und sprechend sein: ad, db, api
  • IDs DARF NICHT Umlaute enthalten: benutzer statt benĂĽtzer

4.3 Labels (SOLLTE)​

  • Domain-Begriffe SOLLTEN auf Deutsch stehen: Benutzer, Vermittler, Sachbearbeiter
  • Technische Begriffe SOLLTEN auf Englisch stehen: API, Database, Processing
  • Status SOLLTE mit Enum-Werten angegeben werden: Staged (0), Completed (3)

5. Datei-Organisation​

project/
└── docs/
└── diagrams/
├── overview.d2
├── overview.png # Rendered output
└── state-machine.d2

Anforderungen:

  • Source (.d2) und Output (.png) MUESSEN gemeinsam committet werden
  • Relative Pfade in Markdown MUESSEN das ./-Prefix verwenden
  • PNG fĂĽr Azure DevOps Kompatibilität

6. Templates​

Vorlagen in ./templates/:

  • architecture-template.d2 - System-Ăśbersicht
  • flowchart-template.d2 - Prozess-Diagramm
  • state-machine-template.d2 - Status-Lifecycle
  • network-template.d2 - Infrastruktur

Kopieren und anpassen fĂĽr neue Diagramme.


7. Rendering​

# PNG (empfohlen fĂĽr Azure DevOps)
d2 diagram.d2 diagram.png

# SVG (optional)
d2 diagram.d2 diagram.svg

7.1 Theme-Empfehlung​

Bei Verwendung der Styleguide-Farbpalette Theme 1 (Neutral Grey) verwenden:

d2 --theme 1 diagram.d2 diagram.png
ThemeIDVerwendung
Neutral Grey1Empfohlen bei Custom Colors - neutrale Basis ohne Farbkonflikte
Default0Nur fĂĽr Diagramme ohne eigene Farbpalette
Colorblind Clear8Alternative fĂĽr Barrierefreiheit

Grund: D2's Default-Theme verwendet eigene Container-Fills die mit der Styleguide-Palette (besonders Orange/Together) kollidieren können.


8. Common Patterns​

8.1 Error Flows​

Fehler-Pfade mit Rot + Gestrichelter Linie darstellen:

...@../../../assets/colors/_colors.d2

user -> api: "Request"
api -> db: "Query"
db -> api: "Timeout" {
style.stroke: ${error-dark}
style.stroke-dash: 3
style.stroke-width: 2
}
api -> user: "500 Error" {
style.stroke: ${error-dark}
style.stroke-dash: 3
}

Konvention: Error-Pfade SOLLTEN mit Label beschriftet werden (z.B. "Timeout", "Validation Failed").

8.2 Authentication Flows​

Auth-Steps mit Lock-Icon oder Protokoll-Label:

...@../../../assets/colors/_colors.d2

client: "Client App" {
style.fill: ${kundensystem}
}
auth: "Auth Server" {
style.fill: ${together}
}
api: "Protected API" {
style.fill: ${cca}
}

client -> auth: "1. Login (OAuth2)" {
style.stroke-width: 2
}
auth -> client: "2. JWT Token"
client -> api: "3. Request + Bearer Token" {
style.stroke-width: 2
}
api -> client: "4. Protected Data"

Konvention: Steps SOLLTEN fĂĽr die Sequenz nummeriert und wichtige Auth-Schritte dicker gezeichnet werden.

8.3 Async Communication​

Queues mit Cylinder-Shape + Dashed Lines:

...@../../../assets/colors/_colors.d2

producer: "Producer" {
style.fill: ${together}
}
queue: "Message Queue" {
shape: cylinder
style.fill: ${neutral}
}
consumer: "Consumer" {
style.fill: ${cca}
}

producer -> queue: "Publish" {
style.stroke-dash: 3
}
queue -> consumer: "Subscribe" {
style.stroke-dash: 3
}

Konvention: Async-Connections MUESSEN gestrichelt sein, Queues SOLLTEN als Cylinder dargestellt werden.

8.4 External Systems​

Externe Systeme (Partner, VU) mit Cloud-Shape oder VU-Farbe:

...@../../../assets/colors/_colors.d2

internal: "TOGETHER API" {
style.fill: ${together}
}
vu: "VU System" {
shape: cloud
style.fill: ${vu}
}
partner: "Partner API" {
shape: cloud
style.fill: ${neutral}
}

internal -> vu: "HTTPS"
internal -> partner: "REST"

Konvention: Externe Systeme SOLLTEN das Cloud-Shape verwenden, Versicherungen die VU-Farbe.


9. Checkliste​

  • Farb-Modus gewählt (Context/Internal/Analysis)
  • Farbpalette importiert (siehe Section 3.2)
  • Barrierefreiheit: Farbe + Stärke/Strichelung/Label kombiniert
  • Legende eingefĂĽgt (bei Status-Farben)
  • Shape-Semantik eingehalten
  • Kontrast-Regeln beachtet (weisse Schrift bei dunklen Farben)
  • Deutsche Domain-Begriffe, englische technische Begriffe
  • PNG-Output committed
  • Relative Pfade mit ./ in Markdown
  • Einfachheit: Könnte das Diagramm aufgeteilt werden?