React + Vite overzicht (team)
Dit document geeft een praktisch overzicht van de React + Vite frontend in deze repository. Doel: snel kunnen onboarden, veilig kunnen wijzigen, en consequent kunnen documenteren.
1. Hoofdstructuur
web/
vite/ # broncode (React + Vite)
index.html # entry voor index-pagina
tijdlijn.html # entry voor tijdlijn-pagina
vite.config.js # Vite build-config (multi-page + output locatie)
package.json # scripts en npm dependencies
src/
main.jsx
App.jsx
pages/
components/
shared/
styles/
react/ # build output (gegenereerd door `npm run build`)
shared/ # gedeelde assets voor legacy html pagina's
index_schema.html # legacy pagina
tijdlijn_schema.html # legacy pagina
Kernidee:
web/viteis de bron van de nieuwe frontend.web/reactis build-output (niet handmatig aanpassen).- Legacy pagina's in
web/bestaan nog naast de nieuwe React-variant.
2. Vite build en routes
Belangrijk uit vite.config.js:
base: "/viz/react/"outDir: "../react"- Multi-page input:
index.htmltijdlijn.html
Na build zijn de belangrijkste routes:
/viz/react//viz/react/tijdlijn.html
3. Map src/ uitgelegd
src/pages/
Container-pagina's met page-level state en orkestratie:
IndexSchemaPage.jsxTijdlijnSchemaPage.jsx
src/components/
UI opgesplitst in herbruikbare stukken.
Submappen:
components/index/- index-specifieke header, controls en visual-panels
components/tijdlijn/- tijdlijn-specifieke header, controls en visual-panels
components/actions/- actiepanelen die gedeeld kunnen worden tussen index en tijdlijn
- huidige componenten:
ActionFormParts.jsxNieuweEntiteitActieBox.jsxRegistratieActieBox.jsxEntiteitActieBox.jsxRepresentatieActieBox.jsx
src/shared/
Gedeelde logica en styling voor beide pagina's:
schemaUtils.js(helpers)SvgPatternDefs.jsx(svg pattern defs)schema-viz.css(basis css)
src/styles/
Pagina-specifieke css:
index-schema.csstijdlijn-schema.css
4. Entrypoints en pagina-opbouw
index.htmllaadt de React index-entry.tijdlijn.htmllaadt de tijdlijn-entry.- Pagina's in
src/pages/gebruiken componenten uitsrc/components/. - Gedeelde util/css blijft in
src/shared/.
Praktische regel:
- Page-level state in
pages/. - Presentatie en deel-ui in
components/. - Algemene helpers nooit dupliceren, maar in
shared/plaatsen.
5. NPM scripts
In web/vite/package.json:
npm run dev- lokale Vite dev servernpm run build- productiebuild naarweb/reactnpm run preview- lokale preview van build
Platformwissel Windows <-> macOS:
node_modulesstaat in.gitignoreen reist dus niet mee via git.- Sommige frontend packages gebruiken platformspecifieke binaries. Een
node_modulesmap die op Windows is opgebouwd, is niet betrouwbaar op macOS, en andersom. - Daarom draaien
npm run dev,npm run buildennpm run previeweerst een kleine check. Alsviteontbreekt of de laatst bekende OS/architectuur niet matcht, wordt automatischnpm installuitgevoerd inweb/vite. - Praktische regel: sync alleen broncode via git; laat dependencies lokaal per machine opnieuw opbouwen.
PowerShell tip:
- Als script execution policy
npmblokkeert, gebruiknpm.cmd.
6. Projectdocumentatie (concreet ingevuld)
Onderstaand is het volledige lijstje uit punt 1 t/m 6, nu concreet voor deze codebase.
6.1 Routing en entrypoints
- Build-output routes:
/viz/react/-> index-pagina/viz/react/tijdlijn.html-> tijdlijn-pagina
- HTML entrypoints in Vite bron:
web/vite/index.htmlweb/vite/tijdlijn.html
- Beide html-bestanden laden dezelfde JS entry:
src/main.jsx. - In
src/App.jsxbepaaltrouteFromPath(window.location.pathname)welke page wordt gerenderd:- pad eindigt op
/tijdlijn,/tijdlijn/of/tijdlijn.html->TijdlijnSchemaPage - anders ->
IndexSchemaPage
- pad eindigt op
6.2 Component-eigenaarschap (welke pagina gebruikt wat)
Index-pagina (src/pages/IndexSchemaPage.jsx) gebruikt:
components/index/SchemaIndexHeadercomponents/index/SchemaIndexControlscomponents/index/IndexRegistratieVisualcomponents/index/IndexRepresentatieVisualcomponents/actions/RegistratieActieBoxcomponents/actions/EntiteitActieBoxcomponents/actions/RepresentatieActieBox
Tijdlijn-pagina (src/pages/TijdlijnSchemaPage.jsx) gebruikt:
components/tijdlijn/SchemaTijdlijnHeadercomponents/tijdlijn/SchemaTijdlijnControlscomponents/tijdlijn/TijdlijnRegistratiePaneelcomponents/tijdlijn/TijdlijnRepresentatiePaneel
Gedeelde/herbruikbare componenten:
components/actions/*is bedoeld voor hergebruik over meerdere pagina's.shared/SvgPatternDefs.jsxenshared/schemaUtils.jszijn pagina-overstijgende bouwblokken.
6.2.1 Actieformulieren en hergebruik
De actie-overlays in de index-pagina zijn opgesplitst in:
NieuweEntiteitActieBox.jsxEntiteitActieBox.jsxRegistratieActieBox.jsxRepresentatieActieBox.jsx
De gedeelde formulieropbouw zit in:
components/actions/ActionFormParts.jsx
Daarin zitten de centrale bouwstenen voor de editstijl:
ActionBodyCardActionTopFieldsActionInlineFieldActionSectionActionRowCardActionFieldsGridActionLabeledEditorFieldActionFieldControlActionGroupedSections
Praktische regel:
- aanpassingen aan de layout of basisgedrag van actieformulieren zoveel mogelijk in
ActionFormParts.jsxdoen - alleen domeinspecifieke flow in de losse
*ActieBox.jsxcomponenten houden
6.3 Dataflow en state
State-eigenaarschap:
- Page-level state leeft in:
IndexSchemaPageTijdlijnSchemaPage
- Child-componenten zijn primair presentational en ontvangen data + callbacks via props.
Belangrijkste stategroepen in IndexSchemaPage:
- Routing/API:
baseUrl - Filter/selectie:
entiteitType,t,registratieId,selectedEntiteitId,geselecteerdeRep - Data:
responseData,registratieData,vizSchema,responseKey - UI-status:
loading,error,schemaError - Actieflow:
actie*,registratieActie*,entiteitNieuwe*,nieuweEntiteit*,relatieSecondaireOpties
Belangrijkste stategroepen in TijdlijnSchemaPage:
- Routing/API:
baseUrl - Selectie/filter:
entityType,entityId - Data:
schema,items,overlayArrows - UI-status:
loading,exporting,copying,error,schemaError
Callbacks met side effects (API/refresh/export):
- Index:
loadSchema,loadDatavoerRegistratieOngedaanMakingUit,voerRegistratieCorrectieUitvoerEntiteitActieUit,voerNieuweEntiteitActieUit,voerActieUitnavigeerNaarRegistratieVanOpvoer
- Tijdlijn:
loadSchema,loadTimelinerenderTimelineCanvas,downloadTimelineAsPng,copyTimelineAsPng
6.4 API-afhankelijkheden
Configuratie:
baseUrlkomt uitimport.meta.env.VITE_API_BASE_URLmet fallbackwindow.location.origin.
Endpoints die door de React+Vite pagina's worden gebruikt:
- Schema/viz:
GET /api/viz/schemaGET /api/viz/entiteit/:typenaam/max-idGET /api/viz/relatie/:typenaam/secondaire-ids
- Registraties en snapshots:
GET /full/registraties?page=:page&size=:sizeGET /full/registraties/:idGET /full/:segment/?t=:tGET /full/:segment/:id?t=:t
- Mutaties:
POST /registratie/
Belangrijke response-verwachtingen in frontendlogica:
fetchAlleRegistratiesverwachtRegistraties+has_more.- Bij mutatieacties wordt registratie-id uit response afgeleid via helperlogica (
Registratieen gerelateerde sleutelvarianten). - Voor entiteiten wordt response-key dynamisch bepaald (bijvoorbeeld
As/Bs/... of andere array key).
6.4.1 Schema-gedreven veldtypes en validatie
De frontend gebruikt de veldmetadata uit GET /api/viz/schema actief voor formuliergedrag.
Relevante veldeigenschappen uit het schema:
naamtypeformatverplichtautoIncrement
Type- en formatinformatie wordt in IndexSchemaPage.jsx doorgezet naar veldDefinities voor:
- gegevenselementgroepen
- relatiegroepen
De centrale validatie en coercion zit in ActionFormParts.jsx:
validatieMeldingVoorVeld(...)coercedWaardeVoorVeld(...)
Wat dit nu concreet doet:
integeraccepteert alleen gehele getallennumberaccepteert alleen geldige decimale getallenbooleanwordt gestuurd viatrue/falsestring + format=datevalideert opYYYY-MM-DDstring + format=date-timevalideert op datum+tijd invoer
Belangrijk ontwerpprincipe:
- live validatie in het formulier en coercion bij preview/submit gebruiken dezelfde centrale helpers
- daardoor kan de UI niet iets "goedkeuren" wat later in de payloadopbouw alsnog stukloopt
Gevolg voor onderhoud:
- als backendtypes of formats veranderen, moet de frontend primair op deze centrale helperlaag worden aangepast, niet per actiebox apart
Concreet voorbeeld:
rel_idofb_idmettype=integer- frontend accepteert alleen gehele getallen
- invoer zoals
1.5ofabcgeeft direct een foutmelding - payload bevat uiteindelijk een JSON number, niet een string
wwwmettype=numberenformat=float64- frontend accepteert decimale getallen
- invoer zoals
12.34is geldig - invoer zoals
12,34ofabcwordt afgekeurd
bbbmettype=boolean- frontend biedt alleen geldige boolean-invoer aan
- payload bevat uiteindelijk
trueoffalse, niet de strings"true"of"false"
datummettype=stringenformat=date- frontend gebruikt datumvalidatie op
YYYY-MM-DD - ongeldige of incompleet getypte datums worden gemeld voordat submit plaatsvindt
- frontend gebruikt datumvalidatie op
6.5 Build/serve-koppeling
- Vite build schrijft naar
web/react(outDir: "../react"). - Backend serveert statische frontend via Gin:
router.Static("/viz", "./web")inmain.go.
- Daardoor worden bestanden uit
web/reactbeschikbaar onder/viz/react/.... base: "/viz/react/"in Vite is nodig zodat assets op de juiste publieke paden laden achter Gin.
6.6 Legacy versus nieuw
Nieuw (React + Vite):
web/vitebevat de actieve React-broncode.web/reactbevat de gegenereerde distributie.- Beide hoofdschermen bestaan in React-vorm:
- index
- tijdlijn
Legacy (naast nieuw, nog aanwezig):
web/index_schema.htmlweb/tijdlijn_schema.htmlweb/shared/*voor legacy gedeelde assets
Praktische status:
- React + Vite is functioneel leidend voor nieuwe wijzigingen.
- Legacy pagina's blijven aanwezig voor referentie/vergelijking en gefaseerde migratie.
7. Werkafspraken voor wijzigingen
Aanbevolen workflow:
- Wijziging maken in
web/vite/src/.... - Lokale build draaien (
npm run buildofnpm.cmd run build). - Controleren of beide pagina's nog renderen.
- Eventuele route-impact en component-impact bijwerken in documentatie.
8. Korte checklist voor nieuwe collega's
- Start in
web/vite/src/pages/om de hoofdflow te begrijpen. - Bekijk daarna
src/components/actions/voor gedeelde actiepanelen. - Lees
src/shared/schemaUtils.jsvoor gedeelde business helpers. - Controleer
vite.config.jsvoor route/base/output gedrag.