This repository contains the source code for the RONL Business API. Full documentation — architecture, deployment guides, API reference, user guides — is published at the IOU Architecture documentation site.
🌐 Live application: mijn.open-regels.nl 🧪 Acceptance environment: acc.mijn.open-regels.nl
The RONL Business API is a secure, multi-tenant platform that enables Dutch municipalities to offer government digital services to residents. It implements the Business API Layer pattern: a security and business-logic layer that sits between a municipality's IAM system and the Operaton BPMN engine.
Instead of exposing Operaton's REST API directly to municipality portals, RONL Business API provides:
- Secure OIDC/JWT token validation against Keycloak
- Multi-tenant isolation per municipality (Utrecht, Amsterdam, Rotterdam, Den Haag)
- Claims mapping from JWT to BPMN process variables
- Role-based authorization (citizen, caseworker, admin)
- Compliance-grade audit logging (BIO, NEN 7510, AVG/GDPR)
- A clean, versioned REST API (
/v1/*) following the Dutch API Design Rules
Resident → Municipality Portal → Keycloak IAM → Business API → Operaton BPMN Engine
The system is hosted across two platforms. Azure hosts the stateless application layer (frontend, backend, PostgreSQL, Redis). A VM at open-regels.nl hosts the services requiring deep customisation or full control (Keycloak, Operaton, Caddy).
| Environment | Frontend | Backend | Keycloak |
|---|---|---|---|
| ACC | https://acc.mijn.open-regels.nl | https://acc.api.open-regels.nl | https://acc.keycloak.open-regels.nl |
| Production | https://mijn.open-regels.nl | https://api.open-regels.nl | https://keycloak.open-regels.nl |
| Layer | Technology |
|---|---|
| Frontend | React 18, TypeScript, Vite, CSS Custom Properties |
| Backend | Node.js 20, Express 4, TypeScript |
| Authentication | Keycloak 23, OIDC Authorization Code Flow |
| Business rules | Operaton BPMN/DMN engine |
| Database | Azure PostgreSQL Flexible Server (audit logs) |
| Cache | Azure Cache for Redis (JWKS, sessions) |
| Hosting | Azure Static Web Apps (frontend), Azure App Service (backend) |
| IAM/BPMN hosting | VM — Caddy, Docker Compose |
| CI/CD | GitHub Actions |
| License | EUPL-1.2 |
All documentation is published at iou-architectuur.open-regels.nl/ronl-business-api/.
Features
- Overview — Business API Layer pattern and core responsibilities
- Multi-Tenant Municipality Portal — Dynamic theming, tenant isolation, feature flags
- Authentication & IAM — Keycloak, DigiD flow, JWT structure
- Business Rules Execution — BPMN/DMN via Operaton
- Security & Compliance — BIO, NEN 7510, AVG/GDPR
- API Design — Dutch API Design Rules, versioning
User Guides
- Logging In (DigiD Flow) — Step-by-step login, assurance levels
- Submitting a Calculation — Test scenarios with expected outcomes
- Caseworker Workflow
- Adding a Municipality
Developer Docs
- Local Development Setup — Prerequisites, JWT token testing, database access, local service URLs
- Backend Development
- Frontend Development — Calling the Business API from a component
- Troubleshooting — Port conflicts, health check failures, 500 errors
- CI/CD
- Deployment Overview — VM troubleshooting, production security checklist
- Keycloak (VM)
- Operaton (VM)
- Backend (Azure App Service)
- Frontend (Azure Static Web Apps)
- Caddy (Reverse Proxy) — Retrieving the Caddyfile from a running VM
References