Mermaid diagramy, PlantUML a C4: diagramy jako kód

1. Co jsou diagramy jako kód

Diagramy jako kód (diagrams as code) jsou diagramy popsané textovým zápisem, ze kterého správný nástroj vygeneruje obrázek. Místo přetahování obdélníků pomocí myši napíšete příkaz „api --> db“ a nástroj se sám postará o rozvržení a propojení prvků.

Podstatný rozdíl je v tom, kde diagram udržujete. Schéma v souboru na sdíleném disku nebo exportovaný obrázek někde v dokumentaci časem přestane odpovídat kódu a málo kdy je jasné, kdo a kdy ho má vlastně aktualizovat. Naproti tomu textový diagram v repozitáři projde revizí spolu se změnou, kterou popisuje, a v diffu je vidět, co se v něm změnilo.

2. Mermaid diagram: zápis, který vykreslí GitHub i GitLab

Mermaid je javascriptová knihovna, která z textu vykreslí vývojový diagram (flowchart), sekvenční diagram, ER diagram databáze, stavový diagram, Ganttův diagram a další. Podle dokumentace GitHubu stačí diagram vložit do bloku kódu označeného jako mermaid v Markdown souboru, issue nebo pull requestu. Stejně ho vykreslí i GitLab.

Syntaxi si můžete vyzkoušet v Mermaid Live Editoru, který ihned při psaní ukazuje náhled. Mermaid zobrazí také Notion, Obsidian nebo wiki v Azure DevOps. Následující vývojový diagram popisuje architekturu malé webové aplikace.

```mermaid
flowchart LR
  zakaznik([Zákazník]) --> web[Webová aplikace]
  web --> api[API]
  api --> db[(PostgreSQL)]
  api --> platby[Platební brána]
  api --> email[E-mailová služba]
```

3. PlantUML: všechny UML diagramy

PlantUML je nástroj napsaný v Javě, který pokrývá všechny běžné UML diagramy (sekvenční, tříd, případů užití, komponent a nasazení) a k tomu například i drátěné modely obrazovek (wireframes). Zápis začíná řádkem @startuml a končí @enduml.

GitHub PlantUML přímo nevykreslí, ale například GitLab.com ano a na vlastní instanci GitLabu ho musí zapnout správce. Lokálně ho umí zobrazit rozšíření ve VS Code nebo IntelliJ, bez instalace pak online server na plantuml.com. Ukázka níže je sekvenční diagram vytvoření objednávky.

@startuml
actor Zákazník
participant "Webová aplikace" as Web
participant API
database PostgreSQL as DB
participant "Platební brána" as Platby
Zákazník -> Web: Odeslat objednávku
Web -> API: POST /orders
API -> DB: uložit objednávku
API -> Platby: vytvořit platbu
Platby --> API: adresa platby
API --> Web: 201 Created
@enduml

4. Mermaid nebo PlantUML?

Pro většinu týmů na GitHubu je výchozí volbou Mermaid, protože ho GitHub standardně podporuje bez dalších nastavení. PlantUML se vyplatí, když potřebujete UML diagramy, které Mermaid moc dobře neumí, anebo ho již používáte v GitLabu.

5. Model C4: architektura ve čtyřech úrovních

Model C4 popisuje architekturu softwaru ve čtyřech úrovních detailu: kontext systému, kontejnery, komponenty a kód. Kontejner zde neznamená Docker kontejner, ale samostatně nasaditelnou část systému, třeba webovou aplikaci, API, databázi nebo mobilní aplikaci.

Model C4 od Simona Browna není nástroj, ale metodika pro popis architektury pomocí diagramů. Nakreslíte je v Mermaidu, v PlantUML nebo třeba ve specializovaném nástroji Structurizr. Většině aplikací stačí první dvě úrovně, diagram komponent se vyplatí u rozsáhlejších částí systému.

6. Které diagramy v projektu opravdu potřebujete

Udržovat se vyplatí diagramy, které pomáhají pochopit proces, struktury, vztahy nebo děje v systému. V době generativní AI to sice vypadá, že přednost má velké množství textů, slovních popisů a vysvětlení, avšak pro člověka jsou diagramy a schémata mnohem rychlejší pro pochopení. V běžné webové nebo mobilní aplikaci jde obvykle o pět typů, které se pak odkazují z dokumentace projektu.

Diagram tříd nebo případů užití obvykle nemusíte ručně udržovat. Diagram tříd ukáže vývojové prostředí z kódu a případy užití se v agilních týmech zapisují jako uživatelské příběhy. Pokud je vyžaduje zadávací dokumentace, vytvořte je pro konkrétní vydání a dál neaktualizujte.

7. Diagramy bez Mermaidu: soubory draw.io a diagramy pomocí AI

Pokud vám textový zápis nevyhovuje, nechte AI vytvořit diagram v draw.io. Soubor .drawio je ve skutečnosti XML, takže ho asistent jako Claude Code, Codex nebo GitHub Copilot upravuje stejně jako zdrojový kód: změní jen prvek, o který ho požádáte, a zbytek diagramu nechá beze změny. Draw.io k tomu nabízí oficiální MCP server a pluginy pro AI asistenty a v editoru má vlastní nástroj, který umí vygenerovat diagram z popisu.

Do repozitáře můžete použít formát .drawio.svg, případně .drawio.png. Oba jsou běžné obrázky, které GitHub zobrazí třeba v README, ale protože obsahují i XML data, umí je rozšíření Draw.io Integration pro VS Code otevřít k úpravám bez exportu.

AI modely jako ChatGPT nebo Gemini umí vytvořit diagram architektury i jako obrázek a můžete v něm upravovat jen vybrané části, aniž by došlo k přegenerování celého diagramu. Takový diagram se hodí pro prezentace nebo pro zákazníka, protože do něj můžete jednoduše vkládat atraktivní infografiku, fotografie a další. Nevýhoda obrázků je, že se jedná o binární formát, takže při uložení v Gitu nelze sledovat dílčí změny, vždy se změní celý soubor.

8. Kde ukládat diagramy

Zdrojový text diagramů patří do repozitáře, typicky do složky docs, ale můžete je umístit i do dokumentačních systémů jako je Confluence, MediaWiki, Notion a další. Diagramy nepotřebují pouze vývojáři, ale i další role v životním cyklu aplikace, jako třeba analytik, projektový manažer, tester, zákazník nebo nový dodavatel při předání projektu.

V AboutTheApp připojíte k aplikaci odkaz na složku s diagramy nebo odkaz na dokumentaci do kategorie Zdrojový kód a architektura a analytické diagramy procesů do kategorie Analýzy a plánování. Odkazy, které nemají vidět všichni, označíte jako privátní. Pokud má zákazník vlastní nasazení s jinou infrastrukturou, připojíte jeho diagram nasazení jen k jeho instalaci a zobrazí se mu na jeho About page. AboutTheApp diagramy nevykresluje, ale drží na ně odkazy.

Časté otázky