Deze documentatie wordt actief uitgebreid — kom regelmatig terug.

Association Register - Architecture

1. Introduction and Goals

Business Context

The Association Register is the core application within the Association Domain that manages the complete lifecycle of association members - from prospective member onboarding through active member management. It serves as the authoritative source for member information, credentials, and verification status.

Primary Goals

Member Lifecycle Management: Handle the complete journey from prospective to active member
Document Verification: Automate verification of legal documents (Chamber of Commerce statements, etc.)
VAD Token Management: Issue and manage Verifiable Association Data (VAD) tokens for members
External Identity Resolution: Provide fast lookup services for LEI, CoC number, and EORI to Client ID mapping
Tiered Access Management: Determine access levels for both members and non-member parties
Audit Trail: Maintain comprehensive records of all member-related activities

Quality Goals

Priority	Quality Attribute	Description	Measurable Goal
1	Security	Protect member data and ensure only authorized access	Zero security breaches, SOC 2 compliance
2	Reliability	System must be available 24/7 for member operations	99.9% uptime SLA
3	Usability	Intuitive interface for both admin and member users	<5 clicks to complete common tasks
4	Maintainability	Easy to update, extend, and debug	<2 hours to deploy updates
5	Performance	Fast response times for all operations	<500ms API response time (p95)

Stakeholders

Internal Stakeholders

Role	Responsibilities	Expectations
CTN Admin Staff	Manage members, approve registrations, resolve issues	Efficient workflow tools, clear visibility into member status
System Administrators	Deploy, monitor, maintain infrastructure	Reliable deployment process, comprehensive logging
Development Team	Build features, fix bugs, maintain codebase	Clean architecture, good documentation, automated testing

External Stakeholders

Role	Responsibilities	Expectations
CTN Participants	Register organizations, manage endpoints, maintain profiles	Self-service portal, quick onboarding, clear error messages
Integration Partners	Integrate with CTN API endpoints	Well-documented API, stable contracts, versioning support
Auditors	Verify security and compliance	Audit logs, access control reports, security documentation
Data Providers	Validate VAD tokens before releasing data	Fast JWKS lookups, reliable VAD tokens
Data Consumers	Obtain VAD tokens and discover endpoints	Discovery API, stable OAuth client-credentials flow

Key Business Goals

Reduce Onboarding Time - From weeks to days for new participants
Increase Trust - Verified identities for all participants
Enable Automation - API-first design for system integrations
Ensure Compliance - GDPR, eIDAS, and industry standards
Support Growth - Scale to 500+ participant organizations

Success Metrics

Metric	Current	Target (6 months)
Participant Onboarding Time	14 days	<3 days
System Uptime	98.5%	99.9%
API Response Time (p95)	800ms	<500ms
User Satisfaction Score	3.2/5	>4.5/5
Active Participant Organizations	45	150+

2. Architecture Constraints

Technical Constraints

Cloud-agnostic (Azure reference): packaged as an OCI image; Azure is the reference cloud
OAuth 2.0 Standard: M2M authentication using client credentials flow
Event-Driven Architecture: notifications via provider webhooks (a CTN-wide event broker is deferred — see Roadmap)
RESTful APIs: External interfaces must follow REST principles

Organizational Constraints

Data Residency: Member data must remain within EU boundaries
Compliance: GDPR compliance for member personal data
Budget: Cost-optimized solution using Azure PaaS services

Standards and Conventions

LEI Standards: Global Legal Entity Identifier Foundation compliance
Chamber of Commerce: Integration with national CoC registries
EUID Standards: The EUID is the European standard for company identification introduced by the European Commission in 2017, combining country code, trade register identifier, and company registration number. It enables identification of companies and their branches across EU Member States through the Business Registers Interconnection System (BRIS). For example: DEK1101R.HRB116737 where DE = Germany, K1101R = Hamburg trade register, HRB116737 = company number
VIES Standard: VIES is the European Commission’s system for validating VAT numbers across the EU, providing a single access point to query VAT numbers from individual member state registries. It allows businesses to validate the existence and validity of VAT numbers for trading partners across the EU, helping ensure correct VAT treatment and reducing fraud . Each EU country has its own VAT number format, but VIES provides centralized validation
EORI Standards**: Economic Operators Registration and Identification compliance**
JWT Standards: Use of JSON Web Tokens for verifiable documents

3. System Scope and Context

Business Context

The Association Register operates within a container transport ecosystem where multiple parties (BCOs, forwarders, terminals, carriers) need to share data securely. The ASR issues VAD tokens proving verified participation; each data provider then decides locally what a given participant may access (no central tier or involvement model in 2026).

Technical Context

Upstream Systems: External verification APIs (Kamer van Koophandel, GLEIF Foundation, EORI API)
Downstream Systems: Data providers (terminals, carriers, logistics providers) that validate VAD tokens before releasing data
Integration Points: OAuth Provider (Keycloak), provider webhooks, email/notification service

4. Solution Strategy

Key Architectural Decisions

Event-Driven Design: Decoupled components communicating via provider webhooks (CTN-wide event broker deferred — see Roadmap)
Microservices Pattern: Separation of concerns with dedicated services for different functions
Cache-First Strategy: Redis cache for high-performance member lookups
Document AI Integration: Automated document processing using Azure AI services

Technology Choices

Frontend:

Frontend stack not yet decided — a React + TypeScript SPA is one candidate (see Coding Standards → Open Questions); a separate ADR will record the choice
Azure Static Web Apps: Hosting with CDN for the portal (reference deployment)
Keycloak (OIDC): User authentication for Admin and Participant portals

Backend:

Quarkus (Java 25+ LTS): REST API packaged as OCI image — per ADR-00002
PostgreSQL 15: Azure Flexible Server for member data
Redis: Caching for high-performance lookups
Azure Blob Storage: Document storage with lifecycle management
Azure Front Door: WAF protection and global load balancing

Authentication & Authorization:

Keycloak (OIDC): Human user authentication (Admin / Participant portals)
Keycloak: Machine-to-Machine (M2M) authentication for external systems
RBAC Model (5 roles):
1. SystemAdmin - All permissions
2. AssociationAdmin - Manage all entities
3. MemberAdmin - Manage own entity
4. MemberUser - Self-service access
5. MemberReadOnly - Read-only access

DevOps:

GitHub Actions: CI/CD with path-filtered triggers; IaC via OpenTofu, Kubernetes deployment via Helm + ArgoCD (GitOps)
JUnit 5 + RestAssured: Backend tests (see Coding Standards §7)
Application Insights: Monitoring and telemetry

5. Building Block View

Core Components

ASR Web UI: Administrator interface for member management
Member Data Storage: PostgreSQL database with member profiles and status
Document Storage: Azure Blob Storage for legal documents and certificates
Verification Logic: Quarkus services (on Kubernetes/AKS) handling document and data verification
Asynchronous Processing: background jobs in the Quarkus services for long-running verification
Event Notifications: provider webhooks (a CTN-wide event broker is deferred — see Roadmap)

External Integrations

API Management: Gateway for external API calls with caching and rate limiting
Key Vault: Secure storage of API keys and certificates
Document Processor: AI-powered document analysis and data extraction
Keystore Cache: Redis cache for LEI/CoC to Client ID mappings

Data Model

The participant data model (entities, relationships, identifier and verification storage) is documented separately in ASR Data Model, with a zoom-friendly ERD-only view. It follows the user/participant separation of ADR-00003: identities and M2M client secrets live in Keycloak, while participants, business identifiers, verifications and dataspace roles live in the ASR, linked to Keycloak by ID.

6. Runtime View

Key Scenarios

Member Onboarding Flow: Document upload → AI processing → External verification (KvK, GLEIF, EORI) → VAD token creation
VAD Token Delivery: Event-driven secure link generation and MFA verification for token delivery
Member Lookup: External party queries LEI/CoC/EORI → Redis cache hit → Client ID and VAD token response
Status Updates: Member status changes → Event publication → Stakeholder notifications

Integration Patterns

Event Sourcing: All state changes published as events
CQRS: Separate read/write models for optimal performance
Circuit Breaker: Protection against external API failures

Link to detailed sequence diagrams: OAuth Provider Member Enrollment Flow

7. Deployment View

Azure Services Architecture (reference deployment)

Compute: Azure Kubernetes Service (AKS) running the Quarkus ASR API + background jobs; Static Web Apps for the portal
Storage: PostgreSQL (Structured Data), Blob Storage (Documents), Redis (Cache)
Integration: API Management (a CTN-wide event broker is deferred — see Roadmap)
Security: Key Vault, Azure Front Door, Managed Identity
AI/ML: Document Intelligence

Scaling Strategy

Horizontal Scaling: Kubernetes Horizontal Pod Autoscaler (HPA)
Database Scaling: PostgreSQL read replicas for query optimization
Cache Strategy: Redis cluster for high availability
CDN: Azure Front Door for global performance

8. Cross-cutting Concepts

Security Patterns

Zero Trust: No implicit trust, verify everything
Managed Identity: Service-to-service authentication without stored credentials
Key Vault Integration: Centralized secret management
API Gateway Security: Rate limiting, IP filtering, OAuth validation

Error Handling

Retry Policies: Exponential backoff for external API calls
Circuit Breaker: Fail-fast pattern for unreliable dependencies
Dead Letter Queues: Failed message handling and recovery
Correlation IDs: End-to-end request tracking

Monitoring and Logging

Application Insights: Comprehensive telemetry and performance monitoring
Azure Monitor: Infrastructure and service health monitoring
Structured Logging: JSON-formatted logs with correlation IDs
Alerting: Proactive notification of issues and SLA breaches

10. Quality Requirements

Performance Requirements

Response Time: <200ms for cached member lookups
Throughput: Support 1000+ concurrent member verification requests
Document Processing: Process uploaded documents within 30 seconds
Event Processing: Event delivery within 5 seconds

Security Requirements

Data Encryption: All data encrypted at rest and in transit
Access Control: Role-based access with least privilege principle
Audit Logging: Complete audit trail of all administrative actions
MFA: Multi-factor authentication for credential delivery

Availability Requirements

Uptime: 99.9% availability (8.7 hours downtime per year)
Recovery Time: RTO of 1 hour, RPO of 15 minutes
Geographic Distribution: Multi-region deployment for disaster recovery

11. Risks and Technical Debts

Current Risks

External API Dependencies: Reliance on Kamer van Koophandel and GLEIF APIs
Data Quality: Inconsistent or outdated information in external systems
Scalability Limits: PostgreSQL scaling limitations with very large member bases
Compliance Changes: Evolving GDPR and data residency requirements

Technical Debts

Legacy Document Formats: Some older document types may not be AI-processable
API Versioning: Need for backward compatibility as system evolves
Monitoring Gaps: Some edge cases in error scenarios not fully covered

Future Improvements

Machine Learning: Implement ML-based fraud detection for document verification
Global Expansion: Support for non-EU legal entity verification systems
Real-time Sync: Live synchronization with external registries
Advanced Analytics: Member behavior and system usage analytics

This document follows the arc42 template and should be updated as the architecture evolves.

In samenwerking met