--- title: Software-architectuur voor mensen en AI-agents documenteeren description: >- Zo documenteert De Voorhoede software-architectuur als Mermaid-diagrammen in tekst, naast de code, zodat developers en AI-agents hetzelfde lezen. language: Dutch url: >- https://www.voorhoede.nl/nl/blog/zo-documenteer-je-software-architectuur-voor-mensen-en-ai-agents/ --- Blog # Zo documenteer je software-architectuur voor mensen en AI-agents By [Jasper](/nl/team/jasper.md) 6 November 2026 ## Categories * [Web performance](/nl/blog/tag/web-performance.md) * [Strategie](/nl/blog/tag/strategie.md) - [Van whiteboard naar repository](#van-whiteboard-naar-repository) - [Mermaid: diagrammen als tekst](#mermaid-diagrammen-als-tekst) - [Een gedeelde taal voor mensen en AI-agents](#een-gedeelde-taal-voor-mensen-en-ai-agents) - [Drie diagrammen die we steeds weer gebruiken](#drie-diagrammen-die-we-steeds-weer-gebruiken) - [Samen diagrammen tekenen](#samen-diagrammen-tekenen) - [Alles is (nog steeds) een systeem](#alles-is-nog-steeds-een-systeem) This post is pretty old, and might contain outdated advice or links. We’re keeping it online, but recommend that you check newer posts to see if there’s a better approach. [All blog posts](/nl/blog.md) Architectuur is belangrijk voor software van hoge kwaliteit, maar het is lastig te bevatten en lastig om over te praten. Bij De Voorhoede schrijven we onze architectuur daarom op als diagrammen in tekst. Zo lezen ons team en hun AI-agents hetzelfde. Toen ik aan de TU Delft mijn afstudeerproject presenteerde om af te studeren als architect en ingenieur, had een van mijn hoogleraren één belangrijk kritiekpunt: voor mij was alles een systeem. Ik vatte dat niet echt op als kritiek. Eerder als compliment :). Er komt natuurlijk veel meer kijken bij het ontwerpen van een gebouw dan systematiek. Maar ik ben altijd geboeid geweest door hoe de onderdelen in elkaar passen. Tegenwoordig werk ik als software-architect, en daar heb ik veel aan die gewoonte. In software bepaalt de architectuur hoe makkelijk een applicatie kan opschalen en zich aanpast aan verandering. Goede architectuur houdt complexiteit laag en beheersbaar. Samenwerken gaat er ook makkelijker door: nieuwe mensen zijn sneller ingewerkt en je kunt eenvoudiger ideeën uitwisselen over hoe iets werkt en waarom. Tegelijk is software-architectuur abstract. Je kunt er niet doorheen lopen zoals door een gebouw. Daardoor is het moeilijk om erover na te denken en nog moeilijker om erover te communiceren. Hier helpen diagrammen. Voor mij zegt een goed systeemdiagram meer dan duizend woorden: welke componenten er zijn, hoe ze samenwerken, welke kant de data op stroomt en in welke volgorde dingen gebeuren. Ik teken ze het liefst op een whiteboard. Maar een whiteboardtekening is een momentopname. Hij verandert niet mee met de code, is lastig te delen en je kunt er onmogelijk samen aan werken als de helft van het team op afstand werkt. En tegenwoordig ziet een deel van het team het whiteboard helemaal niet: de AI-agents waarmee we werken. Hoe komen we dan van een whiteboard naar iets waar we allemaal mee kunnen werken? ## Van whiteboard naar repository In een whiteboardsessie gaat architectuur leven. Een paar blokken, wat pijlen, iemand pakt de stift om een lijn opnieuw te trekken, en ineens ziet iedereen in de ruimte hetzelfde systeem. Maar zodra de sessie voorbij is, verliest de tekening haar waarde. Iemand maakt een foto, die belandt in een chat en daarna kijkt er meestal niemand meer naar. De logische volgende stap is digitaal werken. Online whiteboards zoals Miro, diagramtools zoals draw\.io, of een Figma-export in een wiki. Daarmee kun je diagrammen delen en er (op afstand) samen aan werken. Het grotere probleem blijft: diagram en code groeien uit elkaar. Een diagram dat buiten de code staat, verandert niet mee als de code verandert. Het als afbeelding in de repository committen helpt ook niet, want een PNG kun je niet diffen of reviewen in een pull request. Idealiter staat een diagram naast de code en verandert het mee, net als een README. Wat als we een diagram konden schrijven zoals we code schrijven? ## Mermaid: diagrammen als tekst [Mermaid](https://mermaid.js.org/) is een tekstsyntax voor diagrammen. Je beschrijft de onderdelen en hoe ze met elkaar verbonden zijn, en Mermaid tekent het diagram voor je: flowcharts, sequentiediagrammen, toestandsdiagrammen, ER-diagrammen en meer. Een paar regels tekst zoals deze: ` ```mermaid `\ `flowchart LR`\ `  Browser -- "load app" --> Server`\ `  Server -- "query data" --> DB[(Database)]`\ ` ``` `\ \ Worden zo gerenderd: Omdat het platte tekst is, staat het diagram in een Markdown-bestand direct naast de code. Je kunt het diffen, reviewen in een pull request en de geschiedenis terugzien. En het wordt bijna overal weergegeven waar je het wilt lezen: op GitHub en GitLab, in code-editors, in mijn favoriete notitie-app Obsidian (en andere, zoals Notion), in AI-assistenten zoals Claude en op websites die Mermaid.js gebruiken, zoals deze. Er zijn alternatieven, zoals PlantUML, D2 en Structurizr, en sommige kunnen meer dan Mermaid. Maar geen ervan wordt zo breed ondersteund, en voor documentatie is dat het belangrijkst. Daarom gebruiken we Mermaid al jaren bij De Voorhoede. Mijn collega’s zijn tegenwoordig alleen niet meer de enigen met wie ik diagrammen teken. ## Een gedeelde taal voor mensen en AI-agents Onze coding agents lezen de repository voordat ze code schrijven. Ze kunnen afbeeldingen interpreteren, maar tekst kost minder tokens. En anders dan een PNG of SVG beschrijft een Mermaid-diagram het systeem zonder visuele ruis. Mensen en agents lezen hetzelfde document. Agents lezen diagrammen trouwens niet alleen, ze schrijven ze ook. Als ik architectuur bespreek met een AI-assistent, vraag ik hem het systeem in Mermaid te schetsen. Dat diagram wordt ons gezamenlijke referentiepunt. Zo check ik snel of hij het systeem net zo begrijpt als ik. Diagrammen werken ook goed samen met regels. In een project waar ik nu aan werk, staat in de architectuurdocumentatie naast de diagrammen een korte lijst regels, zoals “Update these diagrams in the same PR that changes the architecture.” Een `AGENTS.md`-bestand verwijst agents naar die documentatie, zodat ze dezelfde regels volgen als het team. Om te voorkomen dat agents diagrammen tekenen met te veel nodes en vage labels, geven we ze dezelfde richtlijnen die we ons team leren (daarover verderop meer). Hoe ziet dat er in de praktijk uit? ## Drie diagrammen die we steeds weer gebruiken De voorbeelden hieronder komen uit een van onze projecten: een webapp die React Admin combineert met Supabase en Cloudflare. Elk diagram beantwoordt een andere vraag. ### Beslisdiagram: waar hoort deze logica thuis? Voor architectuurkeuzes die steeds terugkomen, tekenen we een beslisboom die een nieuwe developer, of een agent, zelf kan volgen. Over dit soort architectuurbeslissingen schreef ik eerder in [Hoe dichtbij de gebruiker moet jouw code draaien?](https://www.voorhoede.nl/nl/blog/hoe-dichtbij-de-gebruiker-moet-jouw-code-draaien.md) ### Deployment-workflow: PR-preview met databasewijzigingen Elke pull request in dit project krijgt een eigen preview. Wijzigt een PR de database, dan krijgt hij ook een eigen databasebranch. Zo kunnen reviewers de wijzigingen testen zonder aan gedeelde data te komen. Het diagram laat de volgorde zien waar het om draait: eerst de database, dan de secrets, dan de preview. De preview wordt alleen gedeployd als de migratie is gelukt. En als de PR wordt gesloten, worden de preview en de databasebranch allebei opgeruimd. We tekenen één diagram per omgeving, zodat je verschillen snel ziet. Een PR-preview zonder databasewijzigingen slaat bijvoorbeeld de branch over en gebruikt de stagingdatabase. ### Request-flow: een lijst ophalen Voor gedrag tijdens runtime werken sequentiediagrammen beter. Ze laten zien wie wie aanroept, in welke volgorde en met welke gegevens. Dit diagram laat zien wat er gebeurt als de app een lijst met orders laadt. Let op de cache-branch, het token van de gebruiker dat wordt doorgegeven en de plek waar autorisatie plaatsvindt: de database filtert de rijen, niet de frontend. Zulke details vergeet je snel, en in het diagram staan ze zwart op wit. Een openbaar voorbeeld uit een van onze projecten vind je in de [README van de TU Delft Spacefinder](https://github.com/voorhoede/tudelft-spacefinder/blob/master/readme.md). De diagrammen daarin laten de architectuur zien en hoe data stroomt tijdens build time en tijdens runtime. We hebben ze ook een vleugje Voorhoede-styling gegeven, voor de mensen die ze lezen (de agents maakt het niet uit). Zulke diagrammen tekenen is een vaardigheid. En die wilden we iedereen in het team meegeven. ## Samen diagrammen tekenen Een paar jaar geleden gaf ik een code class, onderdeel van onze interne lesreeks, over systeemdiagrammen met Mermaid. Het doel: iedereen in het team moest diagrammen in onze projecten kunnen lezen, schrijven en reviewen. We werken nog steeds volgens de afspraken uit die les, en dezelfde richtlijnen geven we nu ook aan onze agents: * **Eén vraag per diagram.** Een diagram dat één vraag beantwoordt, is makkelijker te lezen en makkelijker bij te houden. * **Houd het klein.** Ongeveer 15 nodes of minder. Wordt het groter, splits het dan op. * **Geef verbindingen een werkwoord als label.** “publish”, “subscribe” of “query data” zeggen meer dan een kale pijl. * **Gebruik vormen consequent.** Bijvoorbeeld een cilinder voor elke datastore. * **Gebruik subgraphs voor grenzen.** Zoals een cloudprovider, een back-end, of build time tegenover runtime. * **Schrijf er een paar zinnen bij.** Het diagram laat zien hoe dingen samenhangen, de tekst legt uit waarom. * **Werk diagrammen bij in dezelfde PR.** Verandert de architectuur, dan verandert het diagram mee. Mermaid heeft ook zijn beperkingen. Je hebt weinig controle over de layout, grote diagrammen worden snel onoverzichtelijk en de weergave verschilt net iets per platform. Voor pixelperfecte visuals moet je er niet zijn. Maar om vast te leggen hoe een systeem werkt, heb je dat zelden nodig. ## Alles is (nog steeds) een systeem Het whiteboard blijft mijn favoriete plek om samen over architectuur na te denken. Maar zodra we iets hebben uitgedacht, schrijven we het op in Mermaid, in de repository, naast de code die het beschrijft. Daar komt het op neer: behandel diagrammen als code. Versioneer ze, review ze en pas ze aan als het systeem dat ze beschrijven verandert. Zo blijven ze bruikbaar, voor de mensen in ons team en voor de agents die met hen samenwerken. Deze post is ook beschikbaar als Markdown (via “Copy page” bovenaan), met de diagrammen als tekst. Wil je erover doorpraten met je eigen AI-assistent? Dan kan die ze ook lezen. Architectuur is het systeem achter het scherm. In mijn volgende post kijk ik naar het scherm zelf: hoe we UI-ontwerpen beschrijven als ASCII-wireframes, voor mensen en AI-agents. ## Related blog posts * ### [Je website zichtbaar en begrijpelijk maken voor LLM's](/nl/blog/je-website-zichtbaar-en-begrijpelijk-maken-voor-llms.md) 22 Jul 2026 By James * ### [Digitale Soevereiniteit Heroveren op Europese Infrastructuur](/nl/blog/digitale-soevereiniteit-heroveren-op-europese-infrastructuur.md) 29 Jan 2026 By Luuk * ### [Hoe dichtbij de gebruiker moet jouw code draaien?](/nl/blog/hoe-dichtbij-de-gebruiker-moet-jouw-code-draaien.md) 30 Oct 2025 By Jasper [← All blog posts](/nl/blog.md) [Return to top](#top)