CTS-IL — Technical Reference

Table of Contents

1. Architecture overview
2. Module layout
3. Kafka event bus
4. Camel route inventory
5. REST endpoints
6. Guarantee lifecycle
7. Gate-out decision flow (OPUS)
8. Security
9. Rate limiting
10. Durable state — the poll roster
11. Configuration reference
12. Observability

1. Architecture overview

┌───────────────────────────────────────────────────────────────────┐
│                          CTS-IL  (port 8090)                      │
│                                                                   │
│  ┌──────────────┐  ┌────────────────┐  ┌──────────────────────┐  │
│  │  REST layer  │  │  Camel routes  │  │   Durable state      │  │
│  │  (JAX-RS)    │──│  (integration) │  │  (Redis)             │  │
│  └──────────────┘  └───────┬────────┘  │  ActiveGuaranteeReg. │  │
│                            │           └──────────────────────┘  │
└────────────────────────────┼──────────────────────────────────────┘
                             │
          ┌──────────────────┼──────────────────┐
          │                  │                  │
    ┌─────▼──────┐   ┌───────▼──────┐   ┌───────▼──────┐
    │   Kafka    │   │  Maersk API  │   │ Evergreen API│
    │  (CTS bus) │   │  (REST/OAuth)│   │  (REST/OAuth)│
    └────────────┘   └──────────────┘   └──────────────┘
          │
    ┌─────▼──────┐
    │    CTS     │   (Container Tracking System — not in this repo)
    └────────────┘

    OPUS SmartLink ─────── POST /opus/events ──────────────▶ IL
    SL agents      ─────── POST /sl/guarantee/{id}/... ────▶ IL

The IL makes no decisions and holds no decision cache. Its only persistent state is the poll roster in Redis (see §10); all other durable state lives in CTS or in the Kafka log.

2. Module layout

cts-il/
├── pom.xml
└── src/
    └── main/
        ├── java/com/capitalpay/cgmp/il/
        │   ├── CgmpIlApplication.java          # Quarkus entry point
        │   ├── config/
        │   │   ├── KafkaTopics.java             # Topic name constants + header contract
        │   │   ├── RateLimitProperties.java     # Rate-limit config records
        │   │   ├── MaerskProperties.java
        │   │   ├── EvergreenProperties.java
        │   │   └── OpusProperties.java
        │   ├── model/
        │   │   ├── kafka/                       # Kafka message POJOs (Java records)
        │   │   ├── maersk/                      # Maersk API model objects
        │   │   └── evergreen/                   # Evergreen API model objects
        │   ├── processor/
        │   │   ├── ActiveGuaranteeRegistry.java # Per-carrier active container tracking
        │   │   ├── maersk/
        │   │   │   ├── MaerskGateEventProcessor.java
        │   │   │   ├── MaerskHmacVerifier.java
        │   │   │   └── MaerskDndProcessor.java
        │   │   ├── evergreen/
        │   │   │   ├── EvergreenGateEventProcessor.java
        │   │   │   ├── EvergreenHmacVerifier.java
        │   │   │   └── EvergreenDndProcessor.java
        │   │   └── opus/
        │   │       └── OpusHmacVerifier.java         # verifies inbound webhook HMAC
        │   ├── rest/
        │   │   ├── MaerskWebhookResource.java
        │   │   ├── EvergreenWebhookResource.java
        │   │   ├── OpusEventResource.java
        │   │   ├── SlConfirmationResource.java
        │   │   └── TosRateLimiter.java
        │   ├── routes/
        │   │   ├── maersk/
        │   │   │   ├── MaerskWebhookReceiverRoute.java
        │   │   │   ├── MaerskEventPollerRoute.java
        │   │   │   ├── MaerskDndFetcherRoute.java
        │   │   │   ├── MaerskCertPusherRoute.java
        │   │   │   └── MaerskSubscriptionManagerRoute.java (implied)
        │   │   ├── evergreen/
        │   │   │   ├── EvergreenWebhookReceiverRoute.java
        │   │   │   ├── EvergreenEventPollerRoute.java
        │   │   │   ├── EvergreenDndFetcherRoute.java
        │   │   │   ├── EvergreenCertPusherRoute.java
        │   │   │   └── EvergreenSubscriptionManagerRoute.java
        │   │   ├── opus/
        │   │   │   └── OpusEventReceiverRoute.java
        │   │   └── sl/
        │   │       └── SlReceiverRoute.java
        │   └── security/
        │       ├── MaerskOAuthClient.java
        │       ├── EvergreenOAuthClient.java
        │       └── OpusSmartLinkOAuthClient.java
        └── resources/
            └── application.properties

3. Kafka event bus

3.1 Topic listing

Inbound — guarantee service publishes, IL consumes

The legacy cgmp.guarantee.{issued,claim-decision,settled,closed} topics are no longer consumed by the IL at all — the lifecycle-topic consumers were removed in PBI-047. The IL is driven exclusively by cgmp.il.operation-requested. The guarantee service may still publish those topics for its own purposes; they're simply not part of the IL's contract anymore.

Outbound — IL publishes

3.2 Topic contracts

These topics form the IL ↔ CTS integration surface. Each entry documents the message type, payload fields, what triggers the publish, and the expected consumer action. All timestamps are UTC Instant (ISO-8601). Carrier identity is always duplicated in both the cgmp.slCode Kafka header and a payload field so consumers can route either before or after deserialisation.

Outbound contracts (IL → CTS)

cgmp.gate-events — GateEventMessage

Published whenever the IL receives or polls a container equipment event from any carrier, or when OPUS reports a TOS-level gate event.

Triggers: Maersk or Evergreen webhook delivery; carrier poll cycle (fallback); OPUS VESSEL_DISCHARGE_COMPLETE, CONTAINER_GATE_OUT_CONFIRMED, or FREE_TIME_EXPIRY_WARNING events.

CTS action: Update the container tracking record for the guarantee. A GTOT event starts the demurrage clock; a GTIN event stops it. VESSEL_DISCHARGE_COMPLETE creates the initial tracking record. FREE_TIME_EXPIRY_WARNING surfaces an early discrepancy flag.

cgmp.dnd-charges — DndChargeMessage

Published whenever the IL fetches D&D charges from a carrier API. The same topic is used for all carriers; CTS uses the slCode field and cgmp.slCode header to select the correct claim record type and rate card.

Each ChargeItem contains: chargeType (DEMURRAGE / DETENTION / STORAGE), status (ACCRUING / INVOICED), freeDaysGranted, freeDaysUsed, dailyRate, currency, accruedAmount, invoiced, invoiceNumber.

Triggers: SNAPSHOT — operation-driven via cgmp.il.operation-requested. SCHEDULED — 24-hour timer poll for all rostered containers. MANUAL — admin-driven.

CTS action: Create or update a D&D claim record (MAERSK_DND or EVERGREEN_DND based on slCode). Run the CTS vs SL cross-check against the applicable rate card. Raise a discrepancy flag if amounts diverge beyond the configured threshold.

cgmp.sl.return-confirmation — ReturnConfirmationMessage

Published when an SL agent confirms the container has been physically returned to the depot, or when OPUS reports a CONTAINER_GATE_IN_RETURN event.

Triggers: POST /sl/guarantee/{id}/confirm-return (SL agent REST call) or OPUS CONTAINER_GATE_IN_RETURN event.

Downstream action (not the IL's concern): the guarantee service is the authoritative consumer. The IL doesn't model what state-machine transitions it triggers.

cgmp.sl.receipt-confirmed — ReceiptConfirmedMessage

Published when an SL agent records their payment receipt reference, confirming they have received the guarantee payout.

Triggers: POST /sl/guarantee/{id}/confirm-receipt (SL agent REST call).

CTS action: Verify the confirming agent belongs to the guarantee's SL account. Transition guarantee to CLOSED. Issue the teardown operations to the IL on cgmp.il.operation-requested (UNSUBSCRIBE + ROSTER_REMOVE).

Inbound contract (guarantee service → IL)

The IL's sole inbound command channel is cgmp.il.operation-requested (IlOperationRequestedMessage). The guarantee service requests operations — SNAPSHOT, SUBSCRIBE, UNSUBSCRIBE, ROSTER_ADD, ROSTER_REMOVE — for one or more containers; the IL executes them and reports back on cgmp.il.operation-completed. The full schema, per-operation field requirements, fan-out/rate-limit behaviour, and error codes live in docs/contracts/il-operation-contract.md.

The legacy cgmp.guarantee.{issued,claim-decision,settled,closed} lifecycle topics and their GuaranteeIssuedMessage / GuaranteeClosedMessage payloads were removed from the IL in PBI-047. The IL no longer consumes them; the guarantee service translates its own state transitions into the operations above (see the state-machine mapping in the contract doc).

3.3 Kafka header contract

Every message on the CGMP bus, in both directions, must carry the following Kafka record headers:

The cgmp.slCode header is the primary routing discriminator. IL routes branch on this header before deserialising the message body. This avoids unnecessary JSON parsing on the hot path and ensures routing is deterministic even as body schemas evolve.

CTS responsibility: CTS must set cgmp.slCode on every message it publishes to inbound IL topics.

3.3 Partition key convention

All Kafka partition keys use the format slCode:containerNumber (e.g., MAEU:MSCU1234567). This makes the shipping line visible in the key itself — consumers and monitoring tools can identify the carrier without deserialising the body. Per-container ordering is preserved because slCode is stable for the lifetime of a guarantee.

KafkaTopics.partitionKey(slCode, containerNumber) is the canonical builder.

4. Camel route inventory

4.1 Maersk routes

4.2 Evergreen routes

4.3 OPUS / SmartLink routes

4.4 SL Receiver routes (SL agent → IL)

5. REST endpoints

All endpoints listen on port 8090. Webhook paths are called by external carrier systems; SL confirmation paths are called by authenticated SL agents.

Webhook receivers

POST /webhooks/maersk/events

Receives Maersk equipment event notifications.

• Auth: HMAC-SHA256 in X-Maersk-Signature header (verified in MaerskHmacVerifier)
• Body: Maersk EquipmentEvent JSON (MaerskEquipmentEvent)
• Response: 202 Accepted
• On failure: 400 Bad Request if signature invalid

POST /webhooks/evergreen/events

Equivalent endpoint for Evergreen.

• Auth: HMAC signature in X-Evergreen-Signature (verified in EvergreenHmacVerifier)
• Body: Evergreen EquipmentEvent JSON (EvergreenEquipmentEvent)

POST /tos/events

Receives TOS events from OPUS Terminal via SmartLink.

• Auth: Bearer token in Authorization (OpusBearerTokenVerifier, → 401) and HMAC-SHA256 body signature in X-OPUS-Signature (OpusHmacVerifier, → 400)
• Rate limit: 200 req/min (TosRateLimiter; HTTP 429 beyond cap)
• Body: Map with eventType discriminator
• Handling: gate events relayed to cgmp.gate-events, all other types discarded — see §7. The IL returns no decision; responses are 202 Accepted.

SL agent confirmations

POST /sl/guarantee/{id}/confirm-return

SL agent confirms the container has physically returned to the depot.

• Auth: Bearer token (SL agent identity)
• Body: ReturnConfirmationMessage
  • containerNumber, slCode, returnedAt (ISO 8601), depotCode, confirmedByAgent
• Effect: returnedAt becomes the authoritative D&D boundary. CTS freezes the D&D clock at this timestamp.

POST /sl/guarantee/{id}/confirm-receipt

SL agent confirms all payments were received and provides their accounts-receivable reference. Triggers CTS CLOSED.

• Auth: Bearer token (SL agent identity)
• Body: ReceiptConfirmedMessage
  • containerNumber, slCode, slReceiptRef, confirmedBy, confirmedAt
• Effect: Locks the guarantee. No further claims, payments, or modifications are possible.

6. Guarantee lifecycle

The state machine lives in CTS. IL participates as an event gateway:

                     ┌──────────────┐
                     │   PENDING    │  (CTS internal)
                     └──────┬───────┘
                            │ SNAPSHOT + SUBSCRIBE + ROSTER_ADD ops issued to IL
                     ┌──────▼───────┐
                     │    ARMED     │  container on the IL roster, webhook subscribed
                     └──────┬───────┘
                            │ container gate-out events from IL
                     ┌──────▼───────┐
                     │   ACTIVE     │  (CTS internal — demurrage clock running)
                     └──────┬───────┘
                            │ claim-decision (CTS-internal; SL notified out-of-band)
                     ┌──────▼───────┐
                     │   SETTLED    │  (SL agent verifies wallet via their own channel)
                     └──────┬───────┘
                            │ /confirm-return (DISARM)
                     ┌──────▼───────┐
                     │  DISARMED    │  D&D clock frozen, final charges computed
                     └──────┬───────┘
                            │ /confirm-receipt → UNSUBSCRIBE + ROSTER_REMOVE ops issued to IL
                     ┌──────▼───────┐
                     │   CLOSED     │  webhook subscription deleted, container off the roster
                     └──────────────┘

Key IL responsibilities per transition:

7. OPUS gate-event relay

OPUS is treated like any shipping line under the ingress-only rule: it is an inbound webhook event source only. There is no OPUS API the IL queries, and the IL makes no gating decision — it does not answer truck-arrival requests with ALLOW/HOLD. (The earlier synchronous CONTAINER_GATE_OUT_REQUEST → ALLOW/HOLD machinery and its GuaranteeCache were removed; gating is the terminal operator's concern, driven out-of-band by the guarantee state the operator already holds.)

OPUS POSTs events to POST /tos/events. The resource authenticates each event (HMAC-SHA256 over the raw body and a shared bearer token), enforces the inbound rate cap, then hands the raw bytes to direct:opus-tos-event. The opus-event-receiver route relays the two gate events the IL cares about and discards everything else.

Relay path

OPUS → POST /tos/events
         │
         ▼
  OpusHmacVerifier + OpusBearerTokenVerifier   (1) verify HMAC + bearer token
         │
         ▼
  OpusEventResource → direct:opus-tos-event     (2) rate-limit, then dispatch
         │
         ▼
  opus-event-receiver  .choice() on eventType
         ├─ CONTAINER_GATE_OUT_CONFIRMED ──▶ publish to cgmp.gate-events
         ├─ CONTAINER_GATE_IN_RETURN     ──▶ publish to cgmp.gate-events
         └─ otherwise                    ──▶ discard with warning log

Both relayed events are published to cgmp.gate-events with the Kafka key set to the container number. CTS consumes cgmp.gate-events and applies its own demurrage-clock semantics — the IL attaches no interpretation.

OPUS event types handled

8. Security

HMAC-SHA256 webhook verification

All inbound webhooks (Maersk, Evergreen, OPUS) are verified before any processing occurs. The verifier is the first processor in each route. An invalid signature throws IllegalArgumentException, which the route's onException handler traps, logs, and converts to HTTP 400.

OAuth 2.0 client credentials

Outbound calls to carrier APIs use tokens obtained via the OIDC client credentials flow. Quarkus manages token acquisition and refresh automatically.

Token endpoints are configurable via environment variables (see §11).

SL agent authentication

SL agent REST calls (/sl/guarantee/...) require a valid Bearer token. The confirmedBy field in confirmation messages is populated from the authenticated identity at the REST layer — it is not trusted from the request body.

9. Rate limiting

IL enforces rate limits in both directions to comply with carrier API quotas and protect OPUS.

Outbound — carrier API calls

Rate limits are applied using Camel throttle() with a 60-second window.

Throttle behaviour: Camel throttle applies back-pressure — messages queue, they do not drop. Queued messages will be processed once the rate window clears.

Inbound — OPUS TOS events

OPUS inbound events are capped at 200 req/min (TosRateLimiter). Requests beyond the cap receive HTTP 429. SmartLink is expected to back off and retry (per CGMP×OPUS Integration Spec §8).

SL agent confirmation endpoints (/sl/guarantee/...) are not rate-limited because they are human-initiated, low-frequency events bounded by the number of active guarantees.

10. Durable state — the poll roster

The IL holds no decision-making cache. The only state it persists is the poll roster: the set of containers each SL's pollers must cover. (The earlier GuaranteeCache used for synchronous OPUS gate decisions was removed — see §7.)

ActiveGuaranteeRegistry

A Redis-backed roster, one hash per SL: cgmp:il:roster:{slCode}, with the container number as the hash field and a small RosterEntry (billOfLadingNumber, carrierCustomerCode) JSON as the value. It is read by the polling routes (MaerskEventPollerRoute, EvergreenEventPollerRoute, MaerskDndFetcherRoute, EvergreenDndFetcherRoute) to know which containers to include in each poll cycle when webhooks are unavailable.

The roster is driven exclusively by ROSTER_ADD / ROSTER_REMOVE operations on cgmp.il.operation-requested (the legacy cgmp.guarantee.* @Incoming consumers were removed in PBI-047).

Bounded polling (PBI-055): the timer pollers do not re-read the whole roster each tick — at production roster sizes (≈4,000 containers) a full sweep can't drain within one period, so re-submitting it every tick would compound the throttle backlog without bound. Instead each tick processes a bounded slice via nextSlice, which walks the roster with HSCAN and persists a per-{slCode}:{api} cursor in cgmp:il:sweep-cursor:{slCode}:{api} so successive ticks cover the rest. Slice size = rate-limit × (period / 1 min), sized to drain within the period; full-roster coverage latency is therefore roster / rate (~27 min for Maersk T&T). A per-{slCode}:{api} non-overlap guard (PollSweepGuard) additionally skips a tick whose predecessor is still running. Webhooks (SUBSCRIBE) remain the primary real-time path; the poller is reconciliation. See docs/pbi/PBI-055-cursored-reconciliation-sweep.md.

Durability: because the roster lives in persistent, replicated Redis (AOF in dev via docker-compose; managed Redis in prod via REDIS_URL), it survives IL restarts. A freshly restarted IL reads the existing roster from Redis and resumes polling immediately — no replay or re-arming from the guarantee service is required. See docs/pbi/PBI-054-durable-roster.md.

11. Configuration reference

All sensitive values are injected via environment variables. Non-sensitive defaults are defined in application.properties.

Core

Maersk

Evergreen

OPUS / SmartLink

OPUS has no queryable API, so there is no base-URL / OAuth / outbound config — only the two secrets used to authenticate the inbound webhook.

Rate limits

12. Observability

Health

GET /health — SmallRye Health composite endpoint.

Individual probes:

• GET /health/live — liveness
• GET /health/ready — readiness (includes Kafka connectivity check)

Metrics

GET /metrics — Prometheus text format via Micrometer.

Key metrics to watch:

• Camel route exchange counts and failure rates (camel_exchanges_*)
• Kafka consumer lag (via JMX / Kafka consumer group lag tooling)
• JVM memory and GC (standard Micrometer JVM metrics)
• Custom rate-limit rejection counter (when TosRateLimiter fires 429)

Logging

Default log levels (application.properties):

All route log statements include the container number and/or Kafka record key to allow correlation with CTS logs and carrier API audit trails.