Crash Course Mermaid.js gebruiken in PDM

Doel: Het snel, consistent en foutloos vertalen van de PDM-netwerklogica naar strakke, onderhoudbare Mermaid.js-diagrammen binnen je markdown-bestanden.

Binnen PDM gebruiken we Mermaid.js niet als ‘creatieve tekentool’, maar als een rigide visualisatie-engine. Omdat PDM gebaseerd is op wetmatigheden, hanteren we voor de diagrammen een strikte syntaxis en vaste vormgeving per bouwsteentype.

Zie de Mermaid Docs voor meer informatie over het gebruik van Mermaid.

De basisopzet: richting en vormen

Elk PDM-diagram begint met een definitie van de richting. We gebruiken hoofdzakelijk:

graph TD (Top-Down / Boven naar Beneden): Ideaal voor het Metamodel en hiërarchische structuren.
graph LR (Left-Right / Links naar Rechts): De standaard voor de Flow View en Actor View, omdat we leesrichting en tijdslijnen visualiseren.

PDM Identificatie & Vormen

Geef elk object altijd een unieke, korte ID (bij voorkeur gekoppeld aan de unieke identificatiewet uit PDM) en bepaal de vorm op basis van het type bouwsteen:

Bouwsteen	Mermaid Vorm	Code Voorbeeld	Visueel Effect
Proces (Container)	`{{ ... }}`	`P1{{Proces Inkoop}}`	Stadium / Hexagon
Processtap	`( ... )`	`PS1(Factuur controleren)`	Afgeronde rechthoek
Uitvoerder (Actor)	`([ ... ])`	`A1([Acceptant])`	Stadion-vorm
Informatieobject	`[ ... ]`	`IO1[Klantgegevens]`	Rechte rechthoek
Regel (Kader)	`[ ... ]`	`R1[Wwft-richtlijn]`	Rechte rechthoek (+ styling)

2. Relaties en PDM-Logica (Pijlen)

De manier waarop je objecten verbindt, weerspiegelt de PDM-grammatica. Gebruik de juiste pijltypen om de betekenis zuiver te houden:

Harde informatiestroom (Input/Output): --> (Ononderbroken pijl)
Conditionering / Beïnvloeding (Regels): -.-> (Gestippelde pijl)
Pijlen voorzien van context: Gebruik -- tekst --> of --> |tekst| om de transformatie aan te geven.

Codevoorbeeld: Input -> Stap -> Output

graph LR
    IO_IN[Informatie Input] -->|Brandstof| PS1(Processtap)
    PS1 -->|Produceert| IO_OUT[Informatie Output]

3. PDM Styling (De Huisstijl van de Modelmeester)

Om diagrammen scanbaar te houden, minimaliseren we het kleurgebruik. We gebruiken een rustige, professionele zwart-wit/grijs-architectuur. Regels vallen op door een gestippelde rand (stroke-dasharray).

Voeg deze stylingregel onderaan je Mermaid-code toe (om de Regel-bouwsteen te voorzien van een gestippelde rand):

stroke-width:1px,stroke-dasharray: 5 5

Patroon 1: De Flow View (Chronologie op basis van Brandstof)

In een Flow View verbind je processtappen nooit rechtstreeks met elkaar. Er zit altijd een Informatieobject (gedragen door een Drager) tussen. Stap B kan immers pas starten als de output van Stap A is geleverd.

Goede PDM-syntaxis:

graph LR
    A1([Medewerker]) -.-> PS1
    PS1(Stap 1: Aanvraag invoeren) --> IO1[Aanvraagdossier]
    IO1 --> PS2(Stap 2: Aanvraag beoordelen)
    A2([Acceptant]) -.-> PS2
    style IO1 stroke:#333,stroke-width:1px

Patroon 2: De Actor View (Het Micro-Perspectief)

Bij een Actor View filter je het model rondom één specifieke Uitvoerder. We gebruiken hier vaak een subgraph om de logische grens van de verantwoordelijkheid te trekken.

graph LR
    subgraph Gilde_Acceptatie [Actor View: Acceptant]
        IO_A[Binnenkomend Dossier] --> PS_BEOORDEL_1(Dossier beoordelen)
        R_WWFT[Wwft-kader] -.-> PS_BEOORDEL_1
        ACT_ACC([Acceptant]) -.-> PS_BEOORDEL_1
        PS_BEOORDEL_1 --> IO_B[Akkoord / Afwijzing]
    end

    style R_WWFT stroke-width:1px,stroke-dasharray: 5 5

Geavanceerd: Interactiviteit (Klikbare objecten)

Omdat PDM-documenten online leven (zoals in je wiki of documentatiesite), kun je objecten direct klikbaar maken. Hiermee link je een processtap in een diagram direct door naar de onderliggende specifieke /werkinstructie/ of /view/.

Voeg de click opdrachten helemaal onderaan de Mermaid-code toe (vóór de styling):

    %% Klikbare snelkoppelingen naar de PDM-bronnen %%
    click PS1 "/PDM/views/flow-view/" "Bekijk de Flow View"
    click IO1 "/PDM/fasering/fase-2/genormaliseerde-begrippenlijst/" "Bekijk definitie"

De Gouden Regels voor de PDM-Modelmeester

Gebruik altijd unieke IDs: Als je twee keer PS1 gebruikt in je code, ziet Mermaid dit als exact dezelfde processtap en trekt hij ongewenste lijnen.
Geen tekstuele proza in nodes: Houd de tekst in de vormen kort (maximaal 4-5 woorden). Gebruik eventueel een HTML-break (<br/>) voor een nieuwe regel binnen een vorm.
Houd data en visualisatie gescheiden: Pas de tekst in het diagram pas aan als de Ruwe Werkobjectenlijst of de Genormaliseerde Begrippenlijst is gewijzigd. Het model dicteert de tekening, nooit andersom.