1. Leeswijzer en werkwijze

Dit ERD-hoofdstuk gebruikt een gelaagde weergave. Het doel is niet om alle tabellen en relaties in één groot diagram te persen, maar om steeds vanuit een begrijpelijk overzicht naar meer detail te kunnen navigeren.

De tabeldefinities in de bovenliggende hoofdstukken blijven leidend. Diagrammen, domeinkaarten en indexen zijn ondersteunend en maken vooral zichtbaar hoe de tabellen functioneel samenhangen.

1.1 Weergavelagen

Laag	Doel	Vorm	Wanneer gebruiken
Helikopteroverzicht	Begrijpen welke datadomeinen OefenHub kent en hoe zij globaal samenhangen.	Compact domeindiagram en hubtabel-overzicht.	Bij onboarding, review of impactanalyse.
Domeinkaart	Begrijpen waar je moet beginnen als je een functionele vraag hebt.	Navigatietabel met zoekingang, tabellen en afhankelijkheden.	Wanneer je zoekt naar het juiste deel-ERD.
Deel-ERD per domein	Inzoomen op tabellen binnen één functioneel domein.	Mermaid ERD, eventueel opgesplitst in subdiagrammen.	Wanneer je relaties binnen een domein wilt reviewen.
Cross-domein relaties	Zichtbaar maken waar domeinen elkaar raken.	Geselecteerde relatieoverzichten en thematische diagrammen.	Wanneer een vraag meerdere domeinen raakt.
Relatie-index	Controleerbaar overzicht van harde FK-relaties, soft links, soft links met snapshot en logische verwijzingen.	Tabelvorm, bij voorkeur afgeleid uit de database Markdown.	Wanneer je wilt controleren of een specifieke verwijzing als harde database-FK of als soft link bedoeld is.

1.2 Diagramconventies

• Tabellen worden in diagrammen weergegeven met hun technische Engelse naam.
• Toelichting, keuzes en leeswijzers blijven Nederlandstalig.
• Harde foreign keys worden alleen als normale ERD-relaties weergegeven wanneer zij binnen dezelfde module-, DbContext- en schemagrens vallen of expliciet als uitzondering zijn vastgelegd.
• Soft links worden niet als klassieke harde ERD-relatie gelezen. Zij mogen als gestippelde contextlijn, flowchart of tekstuele verwijzing worden getoond en moeten expliciet als soft link worden benoemd.
• Logische verwijzingen zonder harde FK worden niet automatisch als klassieke ERD-relatie getekend, maar apart benoemd.
• FK + snapshot- en soft link + snapshot-patronen krijgen expliciete toelichting, omdat naast de verwijzing ook historische leesbaarheid belangrijk is.
• Audit- en historytabellen worden alleen in het hoofddiagram getekend wanneer zij essentieel zijn voor het begrip van het domein.
• Cross-domein actorvelden naar Users worden meestal niet in ieder deel-ERD getekend; wanneer zij wel zichtbaar zijn, gelden zij standaard als soft link naar identity, tenzij het brondocument expliciet een harde FK-uitzondering beschrijft.
• Een functionele relatie en een technisch afgedwongen database-FK zijn niet hetzelfde. De domeinpagina's moeten uitleggen dat data inhoudelijk samenhangt, terwijl de EF Core/database-implementatie bewust kiest voor een harde FK, soft link, soft link + snapshot of logische verwijzing.
• De database-informatie blijft de primaire bron voor het datamodel. Eventuele ERD- of Mermaid-weergaven in het TO zijn ondersteunend voor leesbaarheid en vervangen deze brondocumentatie niet.

1.3 Inzoomen zonder onleesbaar totaaldiagram

Inzoomen blijft gewenst, maar gebeurt via onderliggende pagina's. Een totaalbeeld met alle tabellen zou bij de huidige omvang weinig bruikbaar zijn voor review. De gebruikersvriendelijke route is daarom:

1. start bij het helikopteroverzicht;
2. kies via de domeinkaart het juiste domein;
3. bekijk het compacte deel-ERD;
4. zoom binnen de domeinpagina door naar eventuele subdiagrammen;
5. controleer specifieke harde FK's, soft links en logische verwijzingen in de relatie-index;
6. raadpleeg bij twijfel de brontabel in het bovenliggende databasehoofdstuk.

1.4 Wanneer een extra subdiagram nodig is

Een domeinpagina mag meerdere diagrammen bevatten. Splits op zodra één diagram te veel verschillende bedoelingen krijgt. Praktische signalen:

• het diagram toont zowel brondata, auditdata als readmodels door elkaar;
• meer dan ongeveer 12 tot 15 tabellen staan in één diagram;
• een centrale tabel zoals Users of ExerciseRuns trekt bijna alle lijnen naar zich toe;
• de lezer moet eerst meerdere uitzonderingen begrijpen voordat de hoofdrelatie duidelijk wordt.

In die gevallen is een extra subdiagram gebruiksvriendelijker dan een vollediger maar onleesbaar hoofd-ERD.

1.5 Status na consolidatie

Na ronde 9 is de ERD-map een eerste complete documentatieset. Alle hoofddomeinen hebben minimaal een leesroute, een compact diagram of patroonoverzicht, een FK-startpunt en uitleg over brondata, audit/history, readmodels of logische verwijzingen.

De set is nog geen vervanging van de databasehoofdstukken zelf. De ERD-pagina's helpen om de structuur te begrijpen, reviewvragen te stellen en impact van wijzigingen te beoordelen.

1.6 Consistentieregels

Gebruik in vervolgrondes dezelfde woorden in dezelfde betekenis:

Term	Betekenis in deze ERD-map	Niet verwarren met
Brondata	Tabellen die de functionele waarheid van een proces bevatten.	Readmodels of tijdelijke exportmodellen.
Audit/history	Append-only of reconstructiegerichte tabellen die mutaties, actoren of lifecycle-stappen vastleggen.	De actuele bronstatus van een object.
Harde FK	Relationele databaseverwijzing die als foreign key constraint wordt afgedwongen.	Functionele verwijzingen zonder databaseconstraint.
Soft link	Veld dat functioneel naar een andere tabel wijst, maar zonder harde database-FK.	Harde FK of vrije tekstsnapshot.
Soft link + snapshot	Soft link aangevuld met vaste historische contextwaarden.	FK + snapshot binnen hetzelfde domein.
Logische verwijzing	Verwijzing die via applicatielogica wordt gevalideerd, bijvoorbeeld EntityType + EntityId.	Klassieke crow's-foot ERD-relaties.
FK + snapshot	Relatie waarbij een FK wordt gecombineerd met tekstuele momentopname voor historische leesbaarheid.	Vrije duplicatie van actuele brondata.
Readmodel	Afgeleide weergave of teller voor UI, mailbox, frontpage of overzicht.	Nieuwe bron van waarheid.

Bij twijfel geldt: teken alleen een harde FK als ERD-relatie wanneer de database-informatie FK = J en dezelfde modulegrens ondersteunt. Beschrijf soft links en logische verwijzingen als patroon of flowchart, en benoem snapshots expliciet in tekst.