Bronnenoverzicht
Doel
Dit bronnenoverzicht beschrijft de duurzame bronsets die voor het Functioneel Ontwerp van OefenHub worden gebruikt.
Het overzicht is bedoeld als leeswijzer en bronkaart. Het vervangt geen broninhoud en maakt geen nieuwe functionele regels aan. De bronhoudende details blijven staan in usecases, database-informatie, ontwerpbronnen, schermdocumentatie, oefenmodule-documentatie, architectuurdocumentatie en andere duurzame documentatiebronnen.
Dit document ondersteunt drie doelen:
- duidelijk maken welke bronsets duurzaam zijn;
- aangeven waarvoor elke bronset leidend is;
- voorkomen dat tijdelijke werkbestanden, zipnamen of oude extractiestatussen als blijvende FO-bron worden behandeld.
Bronpositie
Het Functioneel Ontwerp is een samenhangend functioneel ontwerpdocument. Het beschrijft de functionele betekenis, domeingrenzen, rolcontexten, autorisatieprincipes, lifecycle-afspraken en samenhang tussen de bronsets.
Het FO is niet de enige bron van waarheid voor alle details.
| Laag | Bronpositie |
|---|---|
| FO-hoofdstukken | Beschrijven functionele samenhang, domeincontracten, grenzen en ontwerpkeuzes. |
| Usecases | Beschrijven concrete procesflows, alternatieve flows, actoracties en functionele voorwaarden. |
| Database-informatie | Beschrijft domeinobjecten, brondata, readmodels, history, audit en opslaggrenzen. |
| Ontwerpbronnen | Beschrijven business rules, statusmodellen, autorisatiematrix, popupregister, command-register en event-register. |
| Schermdocumentatie | Beschrijft schermspecifieke zichtbaarheid, acties, waardelagen, lege toestanden en UI-gedrag. |
| Oefenmodules | Beschrijven modulespecifieke configuratie, payloads, entrypoints, generatie en antwoordinterpretatie. |
| Architectuur | Beschrijft systeemgrens, externe systemen, containers en functionele architectuurcontext. |
| Mockupdocumentatie | Ondersteunt visuele interpretatie, layoutbegrip en schermherkenning. |
| FO-registers | Ondersteunen traceerbaarheid, maar zijn geen zelfstandige domeinbron. |
Duurzame bronsets
De volgende bronsets worden als duurzame bronsets beschouwd.
| Bronset | Primaire functie | Directe ingang |
|---|---|---|
| Usecases | Procesflows, actoren, precondities, alternatieve flows en functionele grenzen. | Usecases |
| Database-informatie | Domeinobjecten, persistentiegrenzen, readmodels, audit, history en technische opslagduiding. | Database-informatie |
| Ontwerpbronnen | Domeinbrede regels, statusmodellen, autorisatiematrix, popupregister, commands en events. | Ontwerpbronnen |
| Schermdocumentatie | Schermdoel, zichtbare gegevens, acties, lege toestanden, waardelagen en schermrequirements. | Schermdocumentatie |
| Oefenmodule-documentatie | Modulespecifieke configuratie, payloadopbouw, vraaggeneratie en antwoordinterpretatie. | Oefenmodules |
| Architectuurdocumentatie | Systeemcontext, containercontext, componentcontext en functionele architectuurgrenzen. | Architectuur |
| Mockupdocumentatie | Visuele en layoutondersteuning bij scherminterpretatie. | Mockups HTML |
| Style-documentatie | Documentatieopmaak, redactiestijl en visuele documentatieconventies. | Style |
| FO-registers | Traceerbaarheid naar usecases, schermen en overige bronnen. | FO-usecase-index |
Niet-duurzame werkbronnen
Tijdelijke werkbronnen worden niet als blijvende FO-bron opgenomen.
Niet-duurzaam zijn onder meer:
- ruwe consolidatiedocumenten die verdwijnen na oplevering van FO, TO en SRS;
- tijdelijke Word-, zip- of extractiebestanden;
- bestandsnamen van aangeleverde archieven;
- overdrachtsnotities uit chats;
- tussenversies met oude FO-versienummers;
- lokale bestandsnamen uit een tijdelijke reviewmap;
- eenmalige exports die later vervangen worden door duurzame markdownbronnen;
- screenshots of PNG’s zonder bijbehorende tekstuele documentatiebron.
Zulke bronnen mogen tijdens extractie of review gebruikt zijn om informatie te begrijpen, maar worden niet als blijvende bronverwijzing in FO-hoofdstukken, registers of bronoverzichten opgenomen.
Wanneer informatie uit een tijdelijke werkbron duurzaam relevant is, moet die informatie worden verwerkt in een duurzame bronset, zoals een usecase, database-informatie, ontwerpbron, schermdocumentatie of FO-hoofdstuk.
Bronvolgorde bij interpretatie
De bronvolgorde hangt af van het type vraag.
Er is dus geen absolute volgorde waarbij één bronset altijd alles overschrijft.
| Vraagtype | Leidende bron | Ondersteunende bronnen |
|---|---|---|
| Procesflow, actoractie of alternatieve flow | Usecases | FO-hoofdstukken, schermdocumentatie, ontwerpbronnen |
| Autorisatie, rolcontext en objecttoegang | Ontwerpbronnen en usecases | FO-hoofdstukken, database-informatie, schermdocumentatie |
| Domeinobject, relatie, readmodel of history | Database-informatie | FO-hoofdstukken, ontwerpbronnen, usecases |
| Statusmodel of toegestane statusovergang | Ontwerpbronnen | Usecases, database-informatie, FO-hoofdstukken |
| Popupkey, popupvariant of themagedrag | Ontwerpbronnen | Usecases, schermdocumentatie, FO-hoofdstukken |
| Schermspecifieke zichtbaarheid of actie | Schermdocumentatie | Usecases, FO-hoofdstukken, mockupdocumentatie |
| Functionele domeinsamenhang | FO-hoofdstukken | Alle duurzame bronsets |
| Moduleconfiguratie en modulepayload | Oefenmodule-documentatie | Database-informatie, FO-22, docentusecases |
| Historische resultaten en runs | Database-informatie | FO-08, FO-18, usecases resultaten/geschiedenis |
| Visuele interpretatie | Schermdocumentatie en mockupdocumentatie | FO-hoofdstukken, style-documentatie |
| Systeemgrens en externe systemen | Architectuurdocumentatie | FO-23, FO-01, database-informatie |
| Requirementsafleiding | SRS | FO-hoofdstukken, usecases, schermdocumentatie |
Conflictregels
Wanneer bronnen elkaar lijken tegen te spreken, geldt de volgende werkwijze.
- Bepaal eerst het vraagtype.
- Bepaal daarna welke bronset voor dat vraagtype leidend is.
- Controleer of het verschil echt inhoudelijk is of alleen een verschil in detailniveau, terminologie of voorbeelddata.
- Gebruik FO-hoofdstukken om samenhang en afbakening te formuleren, niet om bronhoudende details onnodig te dupliceren.
- Leg echte resterende conflicten vast in Open punten en buiten scope.
- Vermijd impliciete keuzes wanneer een productkeuze of scopekeuze nodig is.
Voorbeelden:
| Situatie | Afhandeling |
|---|---|
| Mockup toont een voorbeeldnaam die niet in usecases staat. | Behandel als voorbeelddata, niet als normatieve waarde. |
| Schermdocumentatie toont een knop, maar usecase blokkeert de actie onder voorwaarden. | Usecase en autorisatieregel bepalen of de actie beschikbaar is; schermdocumentatie beschrijft zichtbaarheid en feedback. |
| Database-informatie noemt een readmodel, maar FO beschrijft het als teller. | Database-informatie bepaalt brondata; FO beschrijft de functionele betekenis. |
| Ontwerpbron heeft een statusmodel, maar schermdocumentatie gebruikt een Nederlands label. | Ontwerpbron bepaalt statuswaarden; schermdocumentatie mag gebruikerslabels tonen. |
| Oefenmodule-documentatie beschrijft modulepayloadvelden, maar FO beschrijft generieke payloadprincipes. | Modulebron bepaalt modulespecifieke payload; FO beschrijft platformgrenzen. |
DRY-principe
Het FO volgt het DRY-principe.
Dat betekent:
- usecases worden niet volledig overgeschreven in FO-hoofdstukken;
- schermdocumentatie wordt niet volledig gekopieerd naar FO-hoofdstukken;
- database-informatie wordt niet omgezet naar een tweede datamodel in het FO;
- popupteksten en systeemberichtteksten worden niet gedupliceerd wanneer registers of templates leidend zijn;
- modulepayloads worden niet per module volledig herhaald wanneer oefenmodule-documentatie leidend is;
- mockupwaarden worden niet als definitieve datawaarden overgenomen;
- bronverwijzingen zijn klikbaar en wijzen naar de bron die voor het detail leidend is.
Het FO mag wel samenvatten, duiden en begrenzen. Vooral bij domeinen met veel raakvlakken beschrijft het FO de samenhang tussen bronnen.
Linkbeleid
Bronverwijzingen in FO-hoofdstukken en registers moeten klikbaar zijn.
Omdat bronnenoverzicht.md in docs/functioneel_ontwerp/bronnen staat, gelden voor deze pagina de volgende relatieve linkpatronen.
| Doel | Linkpatroon vanuit deze map |
|---|---|
| Ander FO-hoofdstuk | ../<hoofdstuk>.md |
| FO-register | ../registers/<register>.md |
| Usecases | ../../usecases/... |
| Database-informatie | ../../database_informatie/... |
| Ontwerpbronnen | ../../ontwerpbronnen/... |
| Schermdocumentatie | ../../schermdocumentatie/... |
| Oefenmodules | ../../oefen_modules/... |
| Architectuur | ../../architectuur/... |
| Mockupdocumentatie | ../../mockups_html/... |
| Style-documentatie | ../../style/... |
Gebruik geen tekstuele verwijzingen zoals “zie de docs” zonder link.
Markdownbeleid
Tabellen in bronoverzichten en registers moeten echte markdown-tabellen zijn.
Niet toegestaan:
- platte tekst die bedoeld is als tabel;
- onuitgelijnde kolomkoppen zonder pipes;
- tijdelijke bestandsnamen als bronlabels;
- oude extractiestatussen als inhoudelijke bronpositie;
- versienummers buiten de centrale versieplaats.
Wel toegestaan:
- korte tabellen voor bronsets, vraagtypes, statusduiding en linkpatronen;
- compacte opsommingen voor regels;
- bronlabels die naar duurzame documentatiepaden verwijzen;
- toelichting wanneer een bron alleen ondersteunend is.
Versiebeleid
Versie-informatie hoort centraal in de FO-intro.
Bronoverzichten, registers en hoofdstukken gebruiken geen eigen FO-versienummer.
Zij mogen wel beschrijven dat een bron duurzaam, ondersteunend, visueel of tijdelijk is. Zij noemen geen oude FO-versies als actuele bronstatus.
Wanneer een documentatiepagina inhoudelijk wordt herzien, wordt dit via gitgeschiedenis en commitberichten gevolgd, niet via losse versietekst in elk FO-bestand.
Directe broningangen
Functioneel Ontwerp
| Bron | Link |
|---|---|
| FO intro | Functioneel Ontwerp OefenHub |
| Bronnen en afbakening | 00 — Bronnen en afbakening |
| Productvisie en scope | 01 — Productvisie en scope |
| Open punten en buiten scope | 20 — Open punten en buiten scope |
| Functionele architectuurcontext | 23 — Functionele architectuurcontext |
Registers
| Register | Link |
|---|---|
| Usecase-index | FO-usecase-index |
| Schermindex | FO-schermindex |
| Broninventaris overige markdown | FO-broninventaris overige markdown |
Usecases
| Bron | Link |
|---|---|
| Usecases intro | Usecases |
| Generieke usecases | Generiek |
| Leerlingusecases | Leerling |
| Docentusecases | Docent |
| Ouder-/voogdusecases | Ouder/voogd |
| Beheerderusecases | Beheerder |
Database-informatie
| Bron | Link |
|---|---|
| Database-informatie intro | Database-informatie |
| Identiteit en autorisatie | 01 — Identiteit en autorisatie |
| Relatiebeheer | 02 — Relatiebeheer |
| Docentstructuur en leerlingtoegang | 03 — Docentstructuur en leerlingtoegang |
| Communicatie en notificaties | 04 — Communicatie en notificaties |
| Configuratie en contentbeheer | 05 — Configuratie en contentbeheer |
| Ticket- en meldingsbeheer | 06 — Ticket- en meldingsbeheer |
| Oefenruns, delen en voortgang | 07 — Oefenruns, delen en voortgang |
| Audit, historie en technische uitgangspunten | 08 — Audit, historie en technische uitgangspunten |
| Nog uit te werken tabellen en domeinen | 09 — Nog uit te werken tabellen en domeinen |
Ontwerpbronnen
| Bron | Link |
|---|---|
| Ontwerpbronnen intro | Ontwerpbronnen |
| Autorisatiematrix | Autorisatiematrix |
| Business rules | Business rules |
| Command-register | Command-register |
| Domeinobjecten | Domeinobjecten |
| Event-register | Event-register |
| Header, footer en navigatie | Header, footer en navigatie |
| Popup-register | Popup-register |
| Popup-themes | Popup-themes |
| Statusmodellen | Statusmodellen |
Schermdocumentatie
| Bron | Link |
|---|---|
| Schermdocumentatie intro | Schermdocumentatie |
| Generieke schermen | Generiek |
| Leerling schermen | Leerling |
| Docent schermen | Docent |
| Ouder-/voogd schermen | Ouder/voogd |
| Beheerder schermen | Beheerder |
Oefenmodule-documentatie
| Bron | Link |
|---|---|
| Oefenmodules intro | Oefenmodules |
| Moduleplatform en contract | Moduleplatform en contract |
| Optellen en aftrekken simpel | Optellen en aftrekken simpel |
Architectuur
| Bron | Link |
|---|---|
| Architectuur intro | Architectuur |
| C4 intro | C4-model |
| C4 niveau 1 | System Context |
| C4 niveau 2 | Container Diagram |
| C4 niveau 3 | Component Diagram |
| C4 niveau 4 | Interne bouwblokken |
| Structurizr smoke test | Structurizr smoke test |
Mockupdocumentatie
| Bron | Link |
|---|---|
| Mockups HTML intro | Mockups HTML |
| Generieke mockups | Generiek |
| Leerlingmockups | Leerling |
| Docentmockups | Docent |
| Ouder-/voogdmockups | Ouders |
| Beheerdermockups | Beheerder |
| Modulemockups | Modules |
Gebruik van mockups en PNG’s
Mockups en PNG’s zijn ondersteunende bronnen.
Zij helpen bij:
- visuele interpretatie;
- layoutbegrip;
- herkenning van schermdelen;
- bevestiging van schermrichting;
- controle van responsieve hoofdlijnen;
- validatie of schermdocumentatie nog bij de visuele bron past.
Zij zijn niet leidend voor:
- autorisatie;
- brondata;
- statusmodellen;
- tellerdefinities;
- procesflows;
- databasemodellen;
- exacte productieaantallen;
- definitieve naamgeving wanneer tekstuele bronnen specifieker zijn.
Wanneer mockups en tekstuele bronnen verschillen, wordt vastgesteld of de mockup verouderd is, alleen voorbeelddata toont of een echte functionele afwijking signaleert.
Bronsets per FO-hoofdstuk
De volgende tabel geeft een compacte leeswijzer voor de belangrijkste bronfamilies per FO-hoofdstuk.
| FO-hoofdstuk | Belangrijkste bronsets |
|---|---|
| 00 — Bronnen en afbakening | Bronoverzicht, extractie-notities, registers |
| 01 — Productvisie en scope | Architectuur, usecase-intro’s, FO-domeinhoofdstukken |
| 02 — Rollen, context en autorisatie | Autorisatiematrix, database-identiteit, relatiebeheer, usecases |
| 03 — Applicatieschil, header, footer en navigatie | Header/footer-ontwerpbron, schermdocumentatie, berichten, contentbeheer |
| 04 — Frontpages en overzichtsschermen | Frontpageusecases, schermdocumentatie, contentbeheer, systeemnotificaties |
| 05 — Account, profiel en voorkeuren | Generieke account-/profielusecases, database-identiteit, schermdocumentatie |
| 06 — Relatiebeheer | Relatieusecases, database-relatiebeheer, systeemberichten |
| 07 — Oefencatalogus | Docentstructuur, categoriebeheer, modulebeheer, docentusecases, leerlingtoegang |
| 08 — Leerling oefenen | Leerling-oefenusecases, oefenruns-database, oefenmodules, resultaatbronnen |
| 09 — Gedeelde oefeningen | Leerling gedeelde-oefeningenusecases, oefenruns/delen-database, berichten |
| 10 — Docentfunctionaliteit | Docentusecases, docentstructuur-database, schermdocumentatie docent |
| 11 — Ouder-/voogdfunctionaliteit | Ouder-/voogdusecases, relatiebeheer, oefenruns, live-view |
| 12 — Beheerderfunctionaliteit | Beheerderusecases, beheerder-schermen, database- en ontwerpbronnen |
| 13 — Berichten, communicatie en notificaties | Berichtusecases, communicatie-database, systeemnotificaties, popupregister |
| 14 — Meldingen en ticketafhandeling | Ticketusecases, ticketdatabase, statusmodellen, berichten |
| 15 — Live meekijken | Liveusecases docent/ouder, oefenruns, SignalR-architectuur, audit |
| 16 — Contentbeheer | Contentbeheerusecases, configuratie/content-database, vaste pagina’s |
| 17 — Popups, templates, features en systeemnotificaties | Popupbeheer, systeemberichtenbeheer, features, ontwerpbronnen |
| 18 — PDF-export en resultaatpresentatie | Resultaatusecases, oefenruns, QuestPDF-context, module-export |
| 19 — Functionele beslisregels | Ontwerpbronnen, business rules, autorisatiematrix, statusmodellen |
| 20 — Open punten en buiten scope | Alle domeinhoofdstukken en bekende documentatiepunten |
| 21 — Schermlaag en UX-specificaties | Schermdocumentatie, mockups, popupregister, UX-regels |
| 22 — Oefenmodules en modulepayloads | Oefenmodule-documentatie, modulebeheer, database-oefenruns |
| 23 — Functionele architectuurcontext | C4-architectuur, database, usecase-orkestratie, events/jobs |
Onderhoud van dit bronnenoverzicht
Dit bronnenoverzicht wordt bijgewerkt wanneer:
- een nieuwe duurzame bronset ontstaat;
- een bronset wordt hernoemd of verplaatst;
- een bronset niet langer duurzaam is;
- een register wordt opgesplitst of samengevoegd;
- bronhiërarchie of interpretatieregels wijzigen;
- nieuwe documentatiecategorieën ontstaan;
- tijdelijke bronverwijzingen uit oudere extracties worden verwijderd;
- linkpaden veranderen.
Bij onderhoud gelden de volgende regels:
- verwijs naar duurzame documentatiepaden;
- gebruik relatieve Docusaurus-links;
- verwijder tijdelijke zip-, Word-, chat- of extractienamen uit blijvende bronlijsten;
- houd tabellen compact en onderhoudbaar;
- plaats versie-informatie niet in dit document;
- verplaats echte open beslissingen naar FO-20;
- houd usecase- en schermtraceerbaarheid in de registers.
Kwaliteitscontrole
Voor dit bronnenoverzicht gelden de volgende controles.
| Controle | Verwachting |
|---|---|
| Tijdelijke bronnamen | Niet opnemen als duurzame bron. |
| Oude FO-versiestatussen | Niet opnemen buiten centrale versieplaats. |
| Relatieve links | Klikbaar en passend bij de maplocatie. |
| Bronsets | Alleen duurzame bronsets in hoofdtabellen. |
| Mockups | Ondersteunend aangeduid, niet bronhoudend voor regels. |
| Usecases | Via usecase-index traceerbaar. |
| Schermen | Via schermindex traceerbaar. |
| Overige bronnen | Via broninventaris traceerbaar. |
| Open punten | Alleen in FO-20 of in een expliciet bronhygiënedocument. |
| Tabellen | Echte markdown-tabellen. |
Relatie tot andere FO-brondocumenten
| Document | Relatie |
|---|---|
| 00 — Bronnen en afbakening | Beschrijft de formele afbakening van het FO en de interpretatieregels. |
| 20 — Open punten en buiten scope | Centraliseert resterende keuzes en buiten-scopepunten. |
| Extractie-notities | Beschrijft de werkwijze voor extractie en review. |
| FO-usecase-index | Traceert usecases naar FO-hoofdstukken. |
| FO-schermindex | Traceert schermdocumentatie naar FO-hoofdstukken. |
| FO-broninventaris overige markdown | Inventariseert overige duurzame markdown-/MDX-bronnen. |