A distributed microservice architecture replacing legacy EDI/COREOR messaging with modern API-based container release automation for Belgian ports. Mandatory digital infrastructure under the Port Police Regulations — ensuring every supply chain partner is connected to NxtPort CPu.
NxtPort Certified Pick-up (CPu) is mandatory digital infrastructure for the Port of Antwerp-Bruges. All supply chain partners in the container release process must be connected.
Event Based Data Distribution — external systems subscribe to GCSS Activity Plan events, receiving shipment and Transport Document data on an MQ queue after each event occurs.
ACR tasks can be opened, closed, re-opened, and re-closed. Critical data amendments (vessel, port, release party) trigger re-open. Non-critical changes skip COREOR.
The NxtPort COREOR integration uses only "submit" and "delete" operations. ACR_Closed triggers submit, ACR re-open triggers delete (since the API can't know what changed).
The CPu framework is mandated by Port Police Regulations. All supply chain partners must participate — this is critical digital infrastructure for the port.
Click any node to explore what happens inside. Hit Play to watch the story unfold automatically.
Click any service to explore its classes, responsibilities, and how it connects to the broader system.
The entry point. Consumes GCSS EBDD events, filters for ACR_Open/ACR_Closed at Belgian terminals, extracts 30+ variables from deeply nested TPDoc Avro structures, and maps to clean EquipmentReleaseEvent payloads.
NotificationEventListener — Kafka consumer, event type filter, NxtPort pre-checkPayloadVariableExtractor — Complex TPDoc parsing, Belgian terminal validation, multi-country logicCoreorMapper — TransportDocument → EquipmentReleaseEvent with RKST→APCS terminal resolutionEventDelegator — Kafka producer to dedicated clusterTerminalCodeResolver — Immutable Belgian terminal code mapping (9 terminals)LogMasker — NxtPort credential masking in logsThe brain. Applies complex business rules for new-closed, re-closed, new-open, and re-open scenarios. Persists SUBMIT/DELETE records with dependency tracking. Enriches events with vessel reference data.
EventListener — Kafka consumer, routes ACR_Closed vs ACR_OpenAcrClosedService — New-closed vs re-closed with dependency chainsAcrOpenService — Re-open DELETE processing with SUBMIT dependencyReleaseEventService — Core DB operations, status managementVesselsService — Vessel IMO enrichment with Caffeine cacheEmailService — SendGrid failure notifications (async)GcssApiService — GCSS task creation for error scenariosThe delivery engine. Reactive service that resolves per-subscriber OAuth2 tokens, generates HMAC signatures, POSTs to NxtPort callback URLs, and manages sophisticated retry logic with exponential backoff + jitter.
NotificationSender — Central delivery with OAuth2 + HMAC signingRetryService — Exponential backoff (up to 9 attempts, 30min intervals)RemoteOAuth2AccessTokenService — Per-subscription token cachingAuditService — Kafka audit trail for all delivery attemptsDataAccessService — R2DBC reactive DB status updatesGcssApiService — GCSS task creation on permanent failureThe callback receiver. Exposes POST /notifications webhook for NxtPort to report status. Classifies into 5 scope types: positive, negative, customs-release, customs-scan, or none.
NxtPortIntegrationApiController — POST /notifications endpointNxtportRequestService — Callback vs customs event routingNxtPortRequestTypeValidator — 5-scope classification logicDataAccessService — DB lookups and status updatesGcssApiService — GCSS task creation for customs eventsSendGridEmailService — Rejection alert emailsThe retry bridge. Consumes PushNotificationRetryRecord events from Kafka and persists to the notification_retries table. Provides durable storage for the scheduler to pick up and re-process failed deliveries.
RetryListener — Kafka consumer for retry recordsRetryConsumerService — Maps Avro → JPA entity, persists to DBAbstractKafkaListener — Base class with custom offset managementKafkaRetryConfig — Infinite Kafka retries, limited app retriesThe scheduler. Runs periodic jobs to pick up due retry records from the notification_retries table and resubmits them through the notification pipeline. Ensures no failed delivery is permanently lost.
Click any stage to see exactly what happens at each step in the event processing journey.
GCSS Activity Plan detects an ACR (Arrange Cargo Release) task state change — open, closed, re-open, or re-close. An EBDD event is emitted containing the full Transport Document (TPDoc) as a deeply nested Avro record. The event is published to the shared Kafka cluster topic with a KeySchema containing the segmentID. This is the origin of every container release notification in the system.
Understanding when ACR tasks open, close, re-open, and re-close — and what COREOR submit/delete operations are triggered.
When ACR re-opens, the API cannot know if the change is critical (vessel, port) or non-critical (depot). So a COREOR "delete" is always triggered as a safety measure.
ACR open always expects a subsequent closed. Re-open always expects a subsequent re-closed. This lifecycle drives the dependency chain in the database.
In GCSS, non-critical amendments (e.g. empty container return depot) don't require ACR re-open. These changes aren't relevant to NxtPort and skip the system entirely.
Five Kafka topics across shared and dedicated clusters, all secured with SASL_SSL and SCRAM-SHA-512 authentication.
Two core tables track the complete lifecycle of every container release event.
This isn't just a technical migration — it's mandatory digital infrastructure that impacts every container moving through Belgium's largest port.
Original EDI/COREOR solution by Oguz Aktan and Francisco Javier Moral, with GCSS backend. API development by Koushik Mondal for CPu integration replacing COREOR for NxtPort.
SASL_SSL everywhere. OAuth2 per subscriber. HMAC message signing. Vault-based secrets. Log masking for credentials. Non-root container execution.
OpenTelemetry distributed tracing across all 6 services. Prometheus metrics. Structured logging with Logstash. Grafana dashboards. Complete audit Kafka topic.
Multi-layer retry: immediate (3x), scheduled (9x with backoff), DB persistence, status scheduler. SendGrid alerts + GCSS tasks on permanent failure.