Architectuur

ERP-NL bestaat uit een React/Vite frontend, een FastAPI backend, PostgreSQL, achtergrondworkers en externe services. De backend exposeert interne API-routes onder /api/* en een beperkte publieke API onder /api/v1/*.

Componenten

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

    External --> Bank[Bankconnectoren]
    External --> KVK[KvK API]
    External --> VIES[VIES]
    External --> Keycloak[Keycloak/OIDC]

Frontend

De frontend staat onder frontend/ en gebruikt React, TypeScript, React Router, TanStack Query, Vite, Tailwind en shadcn/Radix componenten. Routes zijn modulegericht en gebruiken guards voor autorisatie en organisatiecontext.

Backend

De backend staat onder backend/ en gebruikt FastAPI, SQLAlchemy en Pydantic. backend/main.py registreert routers voor onder meer auth, users, organizations, payments, payables, commitments, GL, reconciliation, cash application, direct debits, attachments, audit, platform en setup seed jobs.

Bij startup voert de backend migraties uit, maakt standaardbeheeraccounts aan, valideert de runtime database-rol en configureert payment workers.

PostgreSQL

PostgreSQL is de primaire database voor applicatiedata, metadata, audit events, migratiestatus en procesregistratie. De applicatie valideert actief dat runtimeverkeer niet met een superuser- of BYPASSRLS-rol draait.

Externe services

Externe services zijn onder meer bankconnectoren, KvK, VIES, Keycloak/OIDC en object storage. Integraties gebruiken configuratie via omgevingsvariabelen en, waar passend, service-specifieke clients.

Background workers

Background workers verwerken onder meer payment-batch taken, retries en transportpogingen. Workeracties schrijven audit events en gebruiken dezelfde database- en domeinservices als de API-laag.

Migraties

Migraties staan onder backend/migrations/versions/ en worden geregistreerd in backend/migrations/registry.py. Nieuwe migraties horen idempotent te zijn en de legacy baseline niet aan te passen.