Documentation

Hexagonal Architecture

Every service module follows hexagonal architecture (Ports and Adapters, also known as Adapter architecture in some literature) with strict dependency rules. Dependencies always point inward: infrastructure depends on application, application depends on domain, domain depends on nothing.

• Domain - Pure business logic, entities, and value objects. Zero external dependencies.
• Application - Use case orchestration and port definitions. Depends only on Domain.
• Infrastructure - Adapters for external systems: REST, AMQP, databases, Kafka, scheduling. Depends on Application and Domain.

All six production services implement this structure.

Framework SPIs

The SWIM Framework defines 16 Service Provider Interfaces. Each new SWIM service implements only what differs (approximately 700-900 lines), instead of duplicating 5,700+ lines of infrastructure code. The consumer pipeline is built around three orthogonal extension points (EP1, EP2, EP3), described in detail on the Framework page.

Core SPIs (swim-framework-core)

• SwimEventExtractor<T> - Extract metadata from raw payload (Adapter)
• SwimPayloadValidator - Validate payload structure: XSD + business rules (Strategy)
• SwimMessageInterceptor - Optional post-validation processing chain: Drools, BPM (Chain of Responsibility)
• SwimIngressHandler - Receive events from pluggable source into provider pipeline (Strategy)
• SwimSubscription - Common subscription entity interface (Model)
• SubscriptionHeartbeatPublisher - Provider per-subscription heartbeat publishing (Strategy)
• ActiveSubscriptionSupplier - Provider active subscription enumeration (Strategy)
• SubscriptionExpiryStrategy - Provider subscription expiry logic (Strategy)
• SubscriptionRenewalStrategy - Consumer auto-renewal + 404/410 recovery (Strategy)
• ProviderConfiguration - Per-provider connection config: SM URL, AMQP host/port, mTLS paths (Model)
• AbstractKafkaOutboxRouter - Common Kafka outbox routing with counters, DLQ, metrics (Template Method)
• AbstractStreamingInboxConsumer - Technology-agnostic inbox processing orchestration (Template Method)
• AbstractKafkaInboxReader - Kafka-specific batch reading, extend and add @Incoming in application module (Template Method)

Framework Modules (6 Maven modules)

• swim-framework-core - Shared SPIs, enums, DTOs, health checks, security, validation
• swim-framework-consumer - Subscription lifecycle, inbox/outbox, heartbeat tracking, circuit breaker, exponential backoff
• swim-framework-provider - AMQP publishing, per-subscription heartbeat sender, subscription expiry
• swim-framework-persistence-mongodb - MongoDB-specific adapters and index management
• swim-framework-leader-kubernetes - Leader election via Kubernetes lease API
• swim-framework-leader-infinispan - Leader election via Infinispan distributed cache

Design Patterns

• Hexagonal (Ports and Adapters) - All service modules: domain/application/infrastructure layering
• Template Method - AbstractEventDeliveryService.deliver(): load subscriptions, filter, publish
• Strategy - SwimPayloadValidator, SwimOutboxRouter, SwimIngressHandler, LeaderElectionStrategy
• Observer - Vert.x EventBus for inbox/process/outbox pipeline; CDI events for heartbeat timeouts
• Adapter - Subscription Manager client adapts generic lifecycle to service-specific REST APIs
• Builder - Subscription entity construction via Lombok @Builder
• Repository - Generic repositories with Panache (MongoDB and JPA)
• Outbox - Transactional outbox for reliable messaging (persist before dispatch)
• Inbox - Durable reception pattern (persist before ACK)
• Circuit Breaker - ProviderCircuitBreaker: 5 failures, OPEN 30s, HALF-OPEN probe, CLOSED on success

Resilience Patterns

All components adhere to resilience requirements enforced by the framework:

• Persistence Before ACK - Messages persisted to database before broker acknowledgement (zero-loss)
• Circuit Breaker - Per-provider: 5 failures, OPEN 30s cooldown, HALF-OPEN probe (ADR-017)
• Exponential Backoff - SM retry: baseDelay x 2^(attempt-1), max 30s. Inbox recovery with configurable ceiling (ADR-018)
• Programmatic Resilience - SmClientRegistry.executeWithRetry() per provider. 4xx errors NOT retried (ADR-016)
• Idempotency - SHA-256 content hashing via AbstractIdempotencyCache (Caffeine L1 + database L2)
• Inbox Flood Protection - When a consumer resumes after downtime, accumulated AMQP messages are absorbed by the Kafka inbox topic (durable buffer). Controlled consumption prevents overload: max.poll.records limits records per poll, swim.inbox.batch.size limits events per processing batch, and commit-strategy=throttled ensures offsets only advance with completed processing
• Bulkhead - Limits concurrent processing to prevent thread and connection pool exhaustion. Provider ingress: @Bulkhead(100) caps concurrent XML parsing and database persistence. Outbox delivery (consumer and provider): @Bulkhead(250) caps concurrent fan-out routing. Requests beyond the limit are queued or rejected, isolating each processing stage
• DLQ - Failed messages via AbstractDeadLetterService + Kafka DLQ topic
• Per-Subscription Heartbeat - Timeout detection, self-healing via 404/410 recovery (ADR-009)
• Subscription Auto-Renewal - Before expiry, exponential backoff retry on failure
• Leader Election - Only one instance coordinates recovery tasks (Kubernetes lease or Infinispan)
• Multi-Provider - Single consumer connects to N providers simultaneously (ADR-015)

DNOTAM Consumer

Quarkus-based service that consumes Digital NOTAM events from AISP brokers. Implements the Inbox/Outbox Pattern for reliable, asynchronous message processing with guaranteed durability and at-least-once delivery. Hexagonal architecture with domain, application, and infrastructure layers.

Key Capabilities

• Reliable reception: ACK only after persistence (zero-loss)
• XML validation: AIXM 5.1.1 against XSD schemas (SwimXsdValidator)
• Idempotency: SHA-256 content hashing (Caffeine L1 + database L2)
• Kafka routing: 6 topics by business intent (closures, restrictions, surface, airspace, hazards, others)
• Multi-provider: connects to N providers simultaneously (ADR-015)
• Per-subscription heartbeat monitoring with self-healing (404/410 recovery)
• Auto-renewal before subscription expiry
• Circuit breaker per provider (ADR-017)

Internal API (/api/v1)

The consumer acts as a proxy for internal services, abstracting away multi-provider complexity. Internal systems interact only with the consumer's local API, without needing to know how to subscribe, authenticate, or manage connections to external providers.

• Subscription proxy - Create, pause, resume, and delete subscriptions on any configured provider transparently
• Event query - Paginated event retrieval by subscription, date range, or message ID
• WFS proxy - GET /api/v1/features proxies to provider WFS GetFeature endpoints (accepts providerId, filter, typeName)
• Topics - GET /api/v1/topics lists available topics from configured providers
• DLQ and stats - Operational visibility into dead letter queue and aggregate statistics

DNOTAM Provider

Quarkus-based AISP service exposing SWIM-compliant APIs for subscription management, topic discovery, and WFS feature requests. Consumes events from Kafka and publishes to AMQP queues. Hexagonal architecture.

SWIM API (Yellow Profile)

• POST/GET/PUT/DELETE /swim/v1/subscriptions - Full subscription lifecycle
• GET /swim/v1/topics - List available event scenarios
• GET /swim/v1/features - WFS GetFeature with OGC filter (AIXM data)

Internal API (/internal/v1, port 9080, Vert.x)

A dedicated Vert.x HTTP server on port 9080 allows internal systems to distribute DNOTAM messages without dealing with SWIM protocol complexity, AMQP configuration, or subscription management.

• Event trigger - POST /internal/v1/trigger accepts AIXM XML and distributes to all matching active subscriptions
• Pre-flight validation - POST /internal/v1/validate validates AIXM XML against XSD without persisting or publishing
• Subscription summary - GET /internal/v1/subscriptions/summary active/paused counts grouped by scenario, airport, airspace
• Status - GET /internal/v1/status operational health: leader election, XSD readiness, event counters
• OpenAPI - GET /internal/v1/openapi.yaml API specification

Key Capabilities

• Per-subscription heartbeat: JSON to {queue}.heartbeat for ACTIVE and PAUSED subscriptions
• Subscription expiry: automatic termination and purge (subscriptionEnd field)
• Message TTL: 60-second TTL on AMQP messages via JMX (ADR-011)
• Artemis queue provisioning via JMX on subscription creation
• AMQP JWT authentication via Keycloak BearerTokenLoginModule
• JWT role validation per AMQP queue (JwtRoleValidator)

ED-254 Services (Arrival Sequence)

The same framework architecture applied to the EUROCAE ED-254 standard for Extended AMAN (Arrival Manager). FIXM 4.3 data model instead of AIXM. Higher frequency (hundreds/second), tighter latency SLA (<500ms vs <5s), smaller payloads (5-50KB).

ED-254 Consumer

• Same inbox/outbox framework patterns as DNOTAM Consumer
• All 4 ED-254 message types implemented: ArrivalDataType, AMANProviderExceptionType, HeartbeatTechnicalMessage, SubscriptionTechnicalMessage
• Kafka topics: ed254-arrival-sequence-topic, ed254-provider-exception-topic

ED-254 Provider

• REST: POST/DELETE /arrivalSequenceInformation/v1/subscriptions, POST /problems
• CommunicateProblems: bidirectional error reporting, persisted to ed254_problem_reports table, Prometheus metrics
• UnsubscriptionResponse conformance per ED-254 REQ 0150/0155
• 15-second message TTL (LFV Sweden pattern)

FF-ICE Services (Flight Planning)

The same framework architecture applied to the ICAO FF-ICE (Flight and Flow Information for a Collaborative Environment) standard. FIXM 4.3 + FF-ICE 1.1 data model. Built using the swim-consumer-archetype and swim-provider-archetype, demonstrating that new SWIM services can be created from archetypes with minimal custom code.

FF-ICE Consumer

• Same inbox/outbox framework patterns as DNOTAM and ED-254 consumers
• FIXM 4.3 + FF-ICE 1.1 XSD validation via JAXB unmarshaller pool
• 8 Kafka topics by message type: flight-plan, flight-update, operations, trial, submission, data, events, DLQ
• Multi-provider support with subscription renewal (5m check, 1h threshold, 3 retries)
• Per-subscription heartbeat monitoring (15s check, 30s tolerance)
• Idempotency: Caffeine L1 cache (100K entries, 24h TTL) + MongoDB L2
• WFS GetFeature proxy at /swim/v1/features

FF-ICE Provider

• REST: POST/GET /swim/v1/subscriptions, GET /swim/v1/topics, GET /swim/v1/features
• FIXM 4.3 + FF-ICE 1.1 data model with JAXB validation on ingress
• Kafka ingestion from ffice-events-all-topic, AMQP delivery to subscriber queues
• Per-subscription heartbeat (15s interval) and subscription expiry (24h default, 168h max)
• Internal HTTP server (port 9080) for status and event trigger
• OIDC + mTLS authentication

FF-ICE Validators

• Consumer Validator: simulates AISP with Subscription Manager API, event generator, heartbeat publisher
• Provider Validator: 9 conformance test scenarios (API, data model, WFS), mTLS proxy, AMQP capture

Validators

Validators exist to eliminate the dependency on external providers during development and testing. They simulate the counterpart of each SWIM service, allowing teams to develop, debug, and test in isolation. They also enable the creation of chaotic and edge-case scenarios that would be impossible to reproduce against a real provider, preparing the applications for production conditions.

Consumer Validator

Simulates an external provider (AISP/EAD). Exposes a complete Subscription Manager API, generates test events automatically, and includes a built-in AMQP broker with per-subscription heartbeat. Web UI for managing subscriptions and injecting events on demand.

Provider Validator

Simulates an external consumer (ANSP). Subscribes to the provider under test, receives events, and validates conformance against SWIM standards. Web UI with real-time event visualization, Keycloak OAuth2 integration, and mTLS proxy for browser-friendly certificate handling.

Local Infrastructure

Each service includes a compose.yml that starts the full local development infrastructure: message brokers, databases, identity provider, and test validators. Alternatively, Quarkus Dev Services can provision databases and brokers automatically during quarkus:dev.

Two of these components use Red Hat container images hosted on registry.redhat.io, which require authentication before pulling.

Red Hat Container Images

Image	Component	Purpose
registry.redhat.io/rhbk/keycloak-rhel9	Red Hat Build of Keycloak	OAuth 2.0 / OIDC identity provider, AMQP JWT authentication
registry.redhat.io/amq7/amq-broker-rhel9	Red Hat AMQ Broker 7.x	AMQP 1.0 message broker with mTLS and Keycloak JWT auth

Red Hat Developer Account

A Red Hat Developer account is free and grants access to all Red Hat products for development and demonstration purposes. No paid subscription is required to pull these images for local development. Production deployments require an enterprise subscription.

After creating your account, authenticate with the registry once per machine:

Enter your Red Hat Developer credentials when prompted. All subsequent podman compose up commands will pull images automatically.

Yellow Profile (SPEC-170)

EUROCONTROL SPEC-170 defines the technical infrastructure requirements for all SWIM services:

• TLS 1.3 (SWIM-TIYP-0008: TLS 1.2 deprecated) - enforced via cert-manager
• AMQP 1.0 over TLS for publish/subscribe messaging
• mTLS authentication with X.509 client certificates (EACP PKI)
• AMQP JWT authentication via Keycloak BearerTokenLoginModule on Artemis
• Audit logging: failed authentication and access events (JSON structured + Artemis ACK audit plugin)
• Overload protection: rate limiting and queue depth limits (Artemis configuration)
• Health checks: liveness and readiness probes auto-inherited from framework

Observability

All services are instrumented automatically via OpenTelemetry, providing metrics, traces, and logs without manual code changes. The framework injects telemetry at the infrastructure layer.

Metrics (Prometheus)

• Automatic JVM, HTTP, AMQP, and Kafka metrics via Quarkus Micrometer + OpenTelemetry
• Custom business metrics: subscription counts, message throughput, heartbeat status, DLQ depth
• Prometheus scrape endpoints on each service (/q/metrics)

Distributed Tracing (Tempo)

• End-to-end trace propagation across AMQP, Kafka, and REST boundaries
• Trace context injection via OpenTelemetry SDK (W3C Trace Context)
• Tempo as trace backend, queryable from Grafana

Dashboards (Grafana)

• Pre-configured Grafana dashboards for each SWIM service
• Prometheus as data source for metrics visualization
• Tempo as data source for distributed trace exploration
• Subscription lifecycle, message flow, circuit breaker state, and heartbeat health

Test Infrastructure

• JUnit 5 + Mockito for unit business logic
• REST Assured + AssertJ for HTTP integration tests
• Testcontainers for MongoDB, PostgreSQL, Artemis
• Quarkus Dev Services for Redpanda (Kafka) and WireMock
• Playwright for end-to-end browser testing and validation
• Postman collections for API testing and exploration
• JMeter for AMQP load testing