Architectuur

ERP-NL bestaat uit een React/Vite frontend, een FastAPI backend, PostgreSQL, background workers, attachment storage en koppelingen met externe services. De applicatie is modulair opgezet: functionele modules zoals Crediteuren, Betalingen, Grootboek, Inkoop, Subsidies, Verplichtingen, Reconciliatie, Ontvangstenverwerking, Incasso en Integratiebeheer gebruiken gedeelde platformfunctionaliteit voor authenticatie, autorisatie, organisatiecontext, audit, notificaties en bijlagen.

Deze pagina beschrijft de architectuur op hoofdlijnen. Het doel is om ontwikkelaars, beheerders en implementatiepartners te helpen begrijpen hoe ERP-NL is opgebouwd en waar nieuwe functionaliteit logisch thuishoort.

Architectuuroverzicht

flowchart LR
  User[Gebruiker] --> Frontend[React/Vite frontend]
  Frontend --> Backend[FastAPI backend]
  Backend --> Database[(PostgreSQL)]
  Backend --> Storage[Attachment storage]
  Backend --> Workers[Background workers]
  Workers --> Database
  Workers --> External[Externe services]
  Backend --> External

  External --> Bank[Bankconnectoren]
  External --> KvK[KvK API]
  External --> VIES[VIES]
  External --> Keycloak[Keycloak/OIDC]
  External --> ObjectStorage[Object storage]

In gewone taal:

1. De gebruiker werkt in de React frontend.
2. De frontend roept de FastAPI backend aan.
3. De backend verwerkt businesslogica, autorisatie en validatie.
4. PostgreSQL is de primaire database.
5. Background workers verwerken taken die niet direct in de gebruikersrequest hoeven te gebeuren.
6. Externe services worden gebruikt voor authenticatie, bankkoppelingen, validaties, integratieverkeer en opslag.
7. Audit, notificaties en organisatiecontext lopen als generieke platformfuncties door meerdere modules heen.

Belangrijkste componenten

Component	Technologie	Doel
Frontend	React, TypeScript, Vite	Gebruikersinterface
Backend	FastAPI, Python, SQLAlchemy, Pydantic	API, businesslogica en validatie
Database	PostgreSQL	Applicatiedata, audit, metadata en procesregistratie
Background workers	Python services/workers	Asynchrone verwerking, retries en batchtaken
Attachment storage	Lokale opslag, MinIO of S3-compatible storage	Bestandsopslag voor bijlagen
Auth/OIDC	Keycloak of lokale authconfiguratie	Authenticatie en tokenvalidatie
Externe services	Bankconnectoren, KvK, VIES, Oracle, webhooks	Integraties en externe validaties
Documentatiesite	VitePress	Publieke documentatiesite

Componentdiagram

flowchart TD
  Browser[Browser] --> SPA[React SPA]
  SPA --> InternalAPI[Interne API /api]
  ExternalClient[Extern systeem] --> PublicAPI[Publieke API /api/v1]

  InternalAPI --> FastAPI[FastAPI backend]
  PublicAPI --> FastAPI

  FastAPI --> DomainServices[Domeinservices]
  DomainServices --> PostgreSQL[(PostgreSQL)]
  DomainServices --> AttachmentService[Attachment service]
  AttachmentService --> ObjectStorage[Object storage]

  DomainServices --> Audit[Audit events]
  DomainServices --> Notifications[Notificaties]

  FastAPI --> Workers[Background workers]
  Workers --> PostgreSQL
  Workers --> Bank[Bankconnector]
  Workers --> ExternalValidation[Externe validaties]

Dit diagram laat zien dat zowel de frontend als externe clients via API’s naar de backend gaan. De backend gebruikt domeinservices voor businesslogica en schrijft naar PostgreSQL. Generieke functies zoals audit, notificaties en attachments worden door meerdere modules gedeeld.

Frontend

De frontend staat onder:

frontend/

De frontend gebruikt onder andere:

• React;
• TypeScript;
• React Router;
• TanStack Query;
• Vite;
• Tailwind;
• shadcn/Radix componenten.

De frontend is modulegericht opgebouwd. Routes verwijzen naar pagina’s zoals Crediteuren, Betalingen, Grootboek, Inkoop, Subsidies, Verplichtingen, Reconciliatie, Ontvangstenverwerking, Incasso, Integratiebeheer en Platforminrichting.

Frontend verantwoordelijkheden

De frontend is verantwoordelijk voor:

• schermen tonen;
• navigatie tussen modules;
• formulierinput verzamelen;
• filters en tabelweergaven beheren;
• API-calls uitvoeren;
• statuslabels tonen;
• foutmeldingen en successmeldingen tonen;
• autorisatie op routeniveau toepassen;
• organisatiecontext doorgeven;
• gebruikersvoorkeuren zoals tabelinstellingen lokaal bewaren.

De frontend bevat geen definitieve businessregels die de backend moeten afdwingen. De backend blijft verantwoordelijk voor autorisatie, validatie en transactieve verwerking.

Frontend routing

De frontend gebruikt routes per module. Voorbeelden:

Module	Voorbeelden van routes
Crediteuren	/payables/invoices, /payables/suppliers, /payables/payment-process-requests
Betalingen	/payments, /payments/batches, /payments/sepa
Grootboek	/gl/journals, /gl/close, /gl/trial-balance
Boekhouding	/accounting/events, /accounting/errors, /accounting/proposals
Inkoop	/purchasing/requisitions, /purchasing/orders, /purchasing/matching
Subsidies	/subsidies/dashboard, /subsidies/programs, /subsidies/payment-terms
Verplichtingen	/commitments/budgets, /commitments/reservations, /commitments/commitments
Reconciliatie	/reconciliation, /reconciliation/exceptions, /reconciliation/recognition-rules
Ontvangstenverwerking	/receivables, /receivables/receipts, /receivables/exceptions
Incasso	/direct-debits/mandates, /direct-debits/instructions, /direct-debits/batches
Integratiebeheer	/setup/integration, /monitoring/integrations/verwerkingen, /monitoring/integrations/uitzonderingen
Platform	/setup/platform/users, /setup/platform/roles, /monitoring/audit

Routes gebruiken guards voor login en permissions. Daardoor kan een gebruiker alleen schermen openen waarvoor hij of zij rechten heeft.

Backend

De backend staat onder:

backend/

De backend gebruikt onder andere:

• FastAPI;
• SQLAlchemy;
• Pydantic;
• PostgreSQL;
• Python migraties;
• serviceklassen voor businesslogica;
• routerbestanden per functioneel domein.

De backend exposeert:

API-groep	Pad	Doel
Interne applicatie-API	/api/*	Wordt gebruikt door de ERP-NL frontend
Publieke API	/api/v1/*	Bedoeld voor externe machine-to-machine integraties

Backend verantwoordelijkheden

De backend is verantwoordelijk voor:

• authenticatiecontrole;
• autorisatie en permissions;
• organisatie-isolatie;
• businessvalidaties;
• database-transacties;
• domeinservices;
• audit logging;
• foutafhandeling;
• aanroepen van externe services;
• starten of aansturen van achtergrondverwerking;
• OpenAPI-documentatie voor publieke API’s.

Backend routers

De backend registreert routers voor meerdere functionele domeinen. Voorbeelden:

• auth;
• users;
• organizations;
• betalingen;
• crediteuren;
• verplichtingen;
• subsidies;
• Grootboek;
• boekhouding;
• integration control center;
• reconciliatie;
• ontvangstenverwerking;
• incasso;
• attachments;
• audit events;
• notifications;
• platform;
• RBAC;
• setup seed jobs.

Nieuwe functionaliteit hoort in het juiste domein te worden geplaatst. Generieke functionaliteit hoort niet in één module verstopt te worden, maar als platformservice beschikbaar te zijn.

API-laag

De API-laag vormt de grens tussen frontend, externe clients en businesslogica.

flowchart LR
  Frontend[Frontend] --> Api[Interne API routers]
  ExternalClient[Externe client] --> PublicApi[Publieke API]
  Api --> Services[Domeinservices]
  PublicApi --> Services
  Services --> Database[(PostgreSQL)]

Belangrijke uitgangspunten:

• endpoints valideren input;
• endpoints controleren rechten;
• endpoints respecteren organisatiecontext;
• businesslogica zit zoveel mogelijk in services;
• databasewijzigingen zijn transactioneel;
• foutresponses zijn consistent;
• audit wordt vastgelegd voor belangrijke acties.

Domeinservices

Domeinservices bevatten de functionele logica van de applicatie. Routers horen dun te blijven: ze ontvangen requests, controleren toegang en roepen services aan.

Een service kan bijvoorbeeld verantwoordelijk zijn voor:

• factuurvalidatie;
• betaalinstructies aanmaken;
• batchvalidatie;
• SEPA-generatie;
• reconciliatie matching;
• ontvangstenverwerking matching;
• incasso-instructies;
• boekingsvoorstellen;
• auditregistratie;
• notificaties.

Voordeel van domeinservices:

• businesslogica is herbruikbaar;
• workers en API’s kunnen dezelfde logica gebruiken;
• tests kunnen gericht op services worden geschreven;
• regels raken minder verspreid door de codebase.

PostgreSQL

PostgreSQL is de primaire database voor ERP-NL.

PostgreSQL bevat onder andere:

• applicatiedata;
• gebruikers- en organisatiedata;
• financiële transacties;
• facturen;
• betalingen;
• verplichtingen;
• ontvangsten;
• banktransacties;
• audit events;
• notificaties;
• setupdata;
• migratiestatus;
• procesregistratie.

De applicatie valideert actief dat runtimeverkeer niet met een superuser- of BYPASSRLS-rol draait. Dit is belangrijk voor security en organisatie-isolatie.

Database en organisatie-isolatie

ERP-NL ondersteunt meerdere organisaties. Dat betekent dat gegevens logisch gescheiden moeten blijven.

Architectuuruitgangspunten:

• data hoort bij een organisatiecontext waar dat functioneel nodig is;
• API-calls moeten organisatiecontext respecteren;
• gebruikersrechten kunnen afhankelijk zijn van organisatie;
• queries mogen geen gegevens uit andere organisaties lekken;
• tests moeten organisatie-isolatie controleren.

Migraties

Databasewijzigingen worden beheerd via migraties.

Migraties staan onder:

backend/migrations/versions/

De migratieregistratie staat onder:

backend/migrations/registry.py

Uitgangspunten voor migraties:

• migraties zijn versioned;
• migraties horen idempotent te zijn waar mogelijk;
• bestaande baseline-migraties worden niet aangepast;
• nieuwe tabellen, kolommen en indexes worden via nieuwe migraties toegevoegd;
• migraties moeten veilig kunnen draaien bij applicatiestart;
• migraties mogen geen productiedata onbedoeld verwijderen.

Startup

Bij backend startup gebeuren meerdere technische controles en initialisaties.

flowchart TD
  Start[Backend start] --> Config[Configuratie laden]
  Config --> Migrations[Migraties uitvoeren]
  Migrations --> RoleCheck[Runtime DB-rol controleren]
  RoleCheck --> Workers[Workers configureren]
  Workers --> Api[API beschikbaar maken]

Voor beheerders betekent dit:

• databaseconfiguratie moet correct zijn;
• migraties moeten succesvol draaien;
• de runtime databasegebruiker moet veilig zijn;
• secrets en omgevingsvariabelen moeten correct staan;
• workers moeten kunnen starten wanneer processen daarvan afhankelijk zijn.

Background workers

Background workers verwerken taken die niet volledig in een directe gebruikersrequest thuishoren.

Voorbeelden van workerverwerking:

• payment-batch taken;
• retries;
• transportpogingen;
• bankverwerking;
• asynchrone processtappen;
• seed job verwerking;
• verwerking met status en audit.

Workers gebruiken dezelfde database en domeinservices als de API-laag. Daardoor blijven regels en audit consistent.

flowchart LR
  UserAction[Gebruikersactie] --> Backend[Backend API]
  Backend --> Queue[Werkvoorraad of statusregistratie]
  Queue --> Worker[Background worker]
  Worker --> Database[(PostgreSQL)]
  Worker --> Audit[Audit event]
  Worker --> External[Externe service]

Attachments

ERP-NL heeft generieke attachment-functionaliteit.

Bijlagen worden functioneel gebruikt door meerdere modules, bijvoorbeeld bij facturen, verplichtingen of andere objecten.

Architectuurconcept:

Onderdeel	Doel
Attachment metadata	Staat in PostgreSQL
Bestandsinhoud	Staat in lokale opslag, MinIO of S3-compatible object storage
Access log	Registreert toegang of acties waar nodig
Businessobjectkoppeling	Koppelt bijlage aan factuur, verplichting of ander object

De modules hoeven zelf geen bestandsopslag te implementeren. Zij gebruiken de generieke attachment-functionaliteit.

Externe services

ERP-NL kan externe services gebruiken voor validatie, authenticatie, bankkoppelingen, integratieverkeer en opslag.

Voorbeelden:

Service	Gebruik
Keycloak/OIDC	Authenticatie en tokenvalidatie
Bankconnectoren	Betalingen, batches, bankfeedback of transport
KvK API	Leveranciers- of organisatievalidatie
VIES	BTW-nummercontrole
Oracle	Outbound feedback en inbound prototypeflows via Integratiebeheer
Webhooks	CloudEvents naar externe ontvangers
Object storage	Opslag van bijlagen
BIC-data	Bankidentificatie en BIC-keuzevelden

Externe integraties horen via duidelijke clients, services of Integration Control Center-configuratie te lopen. De businesslogica mag niet verspreid raken over willekeurige frontend- of routercode.

Authenticatie

ERP-NL ondersteunt login en tokenvalidatie. Afhankelijk van configuratie kan lokale authenticatie of Keycloak/OIDC worden gebruikt.

Functioneel betekent dit:

• gebruikers moeten zijn ingelogd;
• sessies of tokens worden gecontroleerd;
• verlopen sessies leiden tot opnieuw inloggen;
• externe API-clients gebruiken OAuth2 Client Credentials;
• frontend en backend moeten consistent omgaan met authenticatiefouten.

Autorisatie en RBAC

ERP-NL gebruikt permissions om te bepalen wat gebruikers mogen zien of doen.

Voorbeelden:

• payments.instructions.read;
• payments.batch.read;
• payables.payment_request.read;
• gl.journals.read;
• commitments.budgets.read;
• reconciliation.runs.read;
• cash_application.receipts.read;
• direct_debits.batches.send;
• setup.users.manage;
• audit.read.

Autorisatie wordt op meerdere lagen toegepast:

flowchart TD
  User[Gebruiker] --> RouteGuard[Frontend route guard]
  RouteGuard --> ApiCall[API call]
  ApiCall --> BackendPermission[Backend permission check]
  BackendPermission --> Service[Domeinservice]
  Service --> Data[Data binnen organisatiecontext]

De frontend kan schermen en knoppen verbergen, maar de backend moet de uiteindelijke autorisatie afdwingen.

Audit

Audit is een generieke platformfunctie. Belangrijke acties horen traceerbaar te zijn.

Voorbeelden van auditwaardige acties:

• factuur goedkeuren;
• betaling aanmaken;
• batch verzenden;
• incasso-instructie aanmaken;
• uitzondering oplossen;
• verplichting goedkeuren;
• gebruiker of rol wijzigen;
• setup wijzigen;
• periode afsluiten.

Audit helpt bij:

• controle;
• foutonderzoek;
• compliance;
• incidentanalyse;
• functioneel beheer;
• verantwoording achteraf.

Notificaties

Notificaties zijn generieke platformfunctionaliteit. Modules kunnen notificaties gebruiken om gebruikers te wijzen op acties, waarschuwingen of goedkeuringen.

Voorbeelden:

• betaalactie vraagt goedkeuring;
• factuur heeft aandacht nodig;
• seed job is afgerond of mislukt;
• processtap is mislukt;
• gebruiker moet een taak uitvoeren.

Functionele modules

ERP-NL is functioneel opgebouwd uit modules.

Module	Verantwoordelijkheid
Crediteuren	Leveranciers, crediteurenfacturen en betaalvoorbereiding
Betalingen	Betaalinstructies, batches, SEPA-bestanden en bankfeedback
Grootboek	Grootboek, journaalposten, saldi, boekhouding en periodeafsluiting
Inkoop	Inkoopaanvragen, inkooporders en factuurmatching
Subsidies	Subsidieregelingen, aanvragen, beschikkingen, betaaltermijnen en dossiers
Verplichtingen	Budgetten, reserveringen, verplichtingen en kasverplichtingen
Reconciliatie	Banktransacties matchen en uitzonderingen opvolgen
Ontvangstenverwerking	Ontvangsten koppelen aan openstaande posten
Incasso	Incassomandaten, instructies, batches en uitzonderingen
Integratiebeheer	Connecties, integratiedefinities, mappings, flows, verwerkingen en uitzonderingen
Platform & Beheer	Gebruikers, rollen, organisaties, setup, audit en monitoring

Module-interactie

Modules werken samen via gedeelde objecten, API’s en services.

flowchart LR
  Verplichtingen[Verplichtingen] --> Crediteuren[Crediteuren]
  Crediteuren --> Betalingen[Betalingen]
  Subsidies[Subsidies] --> Crediteuren
  Betalingen --> Reconciliatie[Reconciliatie]
  Debiteuren[Debiteuren] --> CashApplication[Ontvangstenverwerking]
  DirectDebits[Incasso] --> CashApplication
  Crediteuren --> Grootboek[Grootboek]
  Betalingen --> Grootboek
  Verplichtingen --> Grootboek
  Reconciliatie --> Grootboek
  IntegrationControl[Integratiebeheer] --> Crediteuren
  IntegrationControl --> Betalingen
  IntegrationControl --> ExternalSystems[Externe systemen]

Voorbeelden:

• Crediteuren kan betaalinstructies opleveren voor Betalingen;
• Betalingen kan bankfeedback opleveren voor Reconciliatie;
• Ontvangstenverwerking koppelt ontvangsten aan openstaande posten;
• Incasso gebruikt openstaande posten en leidt later tot ontvangsten;
• Verplichtingen kan facturen en betalingen volgen;
• Subsidies zet vrijgegeven betaaltermijnen door naar Crediteuren;
• Integratiebeheer verwerkt externe payloads naar bestaande domeinservices;
• Grootboek verwerkt boekhoudkundige events en journaalposten uit modules.

Inrichting en configuratie

Setupfunctionaliteit is gescheiden van dagelijks gebruik. Beheerders gebruiken setup om basisinrichting te beheren.

Voorbeelden:

Setupgebied	Doel
Platform setup	Gebruikers, rollen, organisaties, bijlagen
Banking setup	Bankrekeningen, connectors, payment schemes, BIC-codes
Integration setup	Connecties, integratiedefinities, mappings, flows, webhooks en Oracle outbound
grootboekinrichting	Grootboek, segmenten, account combinations
Belastinginrichting	BTW- en fiscale inrichting
Verplichtingen setup	Mandaten en autorisatie rond verplichtingen
Boekhoudkundige inrichting	Mapping sets, derivation rules, automation policies

Setupwijzigingen kunnen grote impact hebben. Daarom horen setuprechten beperkt beschikbaar te zijn.

Public API

ERP-NL heeft naast interne API’s ook een beperkte publieke API onder:

/api/v1/*

De publieke API is bedoeld voor externe machine-to-machine integraties.

Documentatie-endpoints:

/api/v1/docs
/api/v1/redoc
/api/v1/openapi.json

De publieke API gebruikt OAuth2 Client Credentials via Keycloak.

Securitymodel

Het securitymodel bestaat uit meerdere lagen.

flowchart TD
  Request[Request] --> Auth[Authenticatie]
  Auth --> Permission[Permission check]
  Permission --> Org[Organisatiecontext]
  Org --> Validation[Inputvalidatie]
  Validation --> Service[Domeinservice]
  Service --> Audit[Audit indien nodig]

Belangrijke security-uitgangspunten zijn:

• authenticatie verplicht voor applicatiefuncties;
• backend autorisatie is leidend;
• organisatie-isolatie afdwingen;
• veilige runtime databasegebruiker;
• geen superuser/BYPASSRLS voor runtimeverkeer;
• secrets via omgevingsvariabelen of secret management;
• audit voor belangrijke acties;
• geen gevoelige informatie in foutmeldingen;
• setuprechten beperken;
• externe API-clients minimale rechten geven.

Deployment

De applicatie bestaat uit meerdere onderdelen die in een omgeving moeten samenwerken.

flowchart TD
  Browser[Browser] --> Frontend[Frontend assets]
  Frontend --> Backend[Backend API]
  Backend --> Database[(PostgreSQL)]
  Backend --> Storage[Object storage]
  Backend --> Workers[Workers]
  Workers --> Database
  Backend --> External[Externe services]

Afhankelijk van de omgeving kan de frontend apart worden geserveerd of door de backend als statische SPA worden aangeboden wanneer een build aanwezig is.

Deploymentvarianten

ERP-NL kan in verschillende omgevingen draaien:

Omgeving	Doel
Lokaal	Ontwikkeling en testen door ontwikkelaars
Codespaces	Browsergebaseerde ontwikkelomgeving
Dev	Doorlopende ontwikkelomgeving
Test	Functionele tests en integratietests
Acceptatie	Gebruikersacceptatie en releasevalidatie
Productie	Werkelijke bedrijfsprocessen

Per omgeving moeten configuratie, secrets, database, storage en externe koppelingen expliciet worden ingericht.

Lokale ontwikkeling

Voor lokale ontwikkeling gebruikt de repository onder andere:

• Python;
• Node.js;
• npm;
• PostgreSQL;
• Vite dev server;
• Uvicorn/FastAPI;
• GitHub Codespaces;
• seed scripts en demo-data.

Typisch lokaal gebruik:

python -m pip install -r backend/requirements-dev.txt
npm install
uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload
npm run dev

Documentatiearchitectuur

De documentatie wordt beheerd met VitePress.

Belangrijke mappen:

Map	Doel
docs/site/	Handgeschreven VitePress-site
docs/reference/	Technische referentiepagina’s en runbooks
docs/generated/	Automatisch gegenereerde technische documentatie

VitePress gebruikt:

docs/site/

als site-root.

Ontwikkelprincipes

Bij nieuwe functionaliteit gelden deze architectuurprincipes:

• plaats functionaliteit in het juiste domein;
• houd businesslogica in backend services;
• gebruik frontend vooral voor interactie en presentatie;
• dwing autorisatie af in de backend;
• respecteer organisatiecontext;
• voeg migraties toe voor databasewijzigingen;
• leg belangrijke acties vast in audit;
• hergebruik platformfuncties voor notificaties en attachments;
• schrijf tests voor nieuwe endpoints en services;
• werk documentatie bij wanneer functionaliteit verandert.

Nieuwe module toevoegen

Een nieuwe module hoort minimaal te bepalen:

• welke objecten de module beheert;
• welke frontendroutes nodig zijn;
• welke backendrouters nodig zijn;
• welke services businesslogica bevatten;
• welke databasewijzigingen nodig zijn;
• welke permissions nodig zijn;
• welke audit events nodig zijn;
• welke notificaties nodig zijn;
• hoe organisatiecontext werkt;
• hoe de module samenwerkt met bestaande modules;
• welke documentatie nodig is.

Nieuwe workflow toevoegen

Een nieuwe workflow hoort expliciet te beschrijven:

flowchart LR
  Trigger[Trigger] --> Validate[Valideren]
  Validate --> Action[Actie uitvoeren]
  Action --> Status[Status bijwerken]
  Status --> Audit[Audit vastleggen]
  Status --> Notify[Notificatie indien nodig]

Voorbeelden van workflowstappen:

• statusovergang;
• goedkeuring;
• validatie;
• batchverwerking;
• foutafhandeling;
• retry;
• handmatige correctie;
• notificatie.

Nieuwe API toevoegen

Bij een nieuwe API hoort minimaal te worden bepaald:

• is het een interne of publieke API;
• welk domein is eigenaar;
• welke request- en responsemodellen zijn nodig;
• welke permissions zijn nodig;
• hoe organisatiecontext wordt bepaald;
• welke validaties nodig zijn;
• welke fouten kunnen optreden;
• of audit nodig is;
• welke tests nodig zijn;
• of OpenAPI-documentatie moet worden bijgewerkt.

Nieuwe databasewijziging toevoegen

Bij een databasewijziging hoort minimaal te worden bepaald:

• welke tabel of kolom nodig is;
• welke indexen nodig zijn;
• welke constraints nodig zijn;
• of data per organisatie gescheiden moet worden;
• of bestaande data gemigreerd moet worden;
• of rollback of herstel mogelijk moet zijn;
• welke tests nodig zijn;
• welke documentatie moet worden bijgewerkt.

Architectuurbeslissingen

Belangrijke architectuurbeslissingen horen als ADR of technische notitie te worden vastgelegd.

Voorbeelden van onderwerpen:

Onderwerp	Waarom vastleggen?
Databasekeuze	Invloed op hosting, queries, migraties en performance
Auth-keuze	Invloed op security, rollen en integraties
Modulegrenzen	Voorkomt overlap tussen domeinen
Public API strategy	Bepaalt stabiliteit van externe contracten
Storagekeuze	Bepaalt opslag, security en backups
Workerstrategie	Bepaalt betrouwbaarheid van asynchrone processen
RBAC-model	Bepaalt beheerbaarheid en security

Veelvoorkomende vragen

Waar staat de frontend?

In frontend/.

Waar staat de backend?

In backend/.

Waar staan migraties?

In backend/migrations/versions/.

Waar staat de documentatiesite?

In docs/site/.

Waar staan technische referenties?

In docs/reference/.

Waar staat gegenereerde documentatie?

In docs/generated/.

Welke database gebruikt ERP-NL?

PostgreSQL.

Welke backendtechnologie gebruikt ERP-NL?

FastAPI met SQLAlchemy en Pydantic.

Welke frontendtechnologie gebruikt ERP-NL?

React, TypeScript en Vite.

Hoe worden rechten afgedwongen?

Frontendroutes gebruiken guards, maar de backend moet de definitieve autorisatie afdwingen.

Hoe worden externe integraties aangesloten?

Via backendservices of clients, niet rechtstreeks vanuit willekeurige frontendcode.

Aandachtspunten

Let bij architectuurwijzigingen op het volgende:

• voorkom dat businesslogica alleen in de frontend terechtkomt;
• voorkom dubbele logica in meerdere modules;
• plaats gedeelde functies in platformservices;
• leg belangrijke acties vast in audit;
• test organisatie-isolatie;
• voeg migraties toe in plaats van bestaande migraties te wijzigen;
• gebruik duidelijke permissions;
• houd publieke API’s stabieler dan interne API’s;
• documenteer belangrijke ontwerpkeuzes;
• werk documentatie bij bij functionele wijzigingen.

Accounting-eigenaarschap tijdens de extractie

De bestaande generieke Accounting-modellen staan in backend/accounting/models/entities.py; backend.model_registry registreert ze eenmaal. Statussen, commands en HTTP-schema's staan onder backend/accounting/domain/ en backend/accounting/schemas/. Imports vanuit Commitments verwijzen naar deze eigenaar; de oude ORM-re-export is verwijderd. Deze stap verandert geen databasetabellen. De services en routers gebruiken voorlopig nog de bestaande Commitments-implementatie. De resterende cutover en het normatieve doel staan in specs/accounting/implementation-plan.md.

Generieke Accounting-opslag staat nu in backend/accounting/repository.py. Leveranciersopzoekingen en documentnummering blijven in backend/commitments/repository_source_support.py. De bestaande Commitments-service gebruikt de native repository nog in zijn samenstelling; de publieke servicegrens en JournalTarget-adapter volgen in de cutover.

De configuratieservice backend.accounting.services.configuration.AccountingConfigurationService beheert nu de bestaande accountingregels, journaalregels, mappings en rekeningafleiding. Setup-endpoints gebruiken deze service rechtstreeks. Configuratiefouten hebben het type AccountingDomainError; nieuwe configuratie-audits vallen onder ACCOUNTING en delen de transactie van de wijziging. Bestaande audithistorie wordt niet herschreven. Bronpublicatie en bronaudits blijven bij Commitments. De nieuwe RuleSet-hiërarchie en immutable versies behoren nog tot de resterende cutover.

Slice 2 voegt de native RuleSet- en representationmodellen toe en vervangt AccountingMethod door EventAccountingRules. De configuratietabel is in de migratie rechtstreeks hernoemd naar acc_event_accounting_rules, met behoud van UUID's, grafen en auditvelden. Setup maakt expliciete RuleSet-releases aan en koppelt eventregels daaraan. PostgreSQL bewaakt releaseversies en organisatie-/parent-consistente representation-pins. De resolver, volledige configuratie-immutability en representationgedreven verwerking volgen in slice 3; de overige tabel- en historische eventmigraties blijven onderdeel van slice 5.