Maven Module Structure

Maven Module Structure

Overview

The project is organized into Maven submodules. The parent POM acts as a BOM (Bill of Materials) for dependency version management across all modules.

Spring is used only in the webapp module (Spring Boot application entry point and REST controllers). All other modules are framework-independent and use ph-db for JDBC-based database access, following the same patterns as phoss-smp.

Module Dependency Diagram

graph TD
    parent[phoss-ap-parent]
    api[phoss-ap-api]
    basic[phoss-ap-basic]
    db[phoss-ap-db]
    fwd[phoss-ap-forwarding]
    sentry[phoss-ap-sentry]
    otel[phoss-ap-otel]
    validation[phoss-ap-validation]
    dirsender[phoss-ap-dirsender]
    core[phoss-ap-core]
    webapp[phoss-ap-webapp]

    api --> parent
    basic --> parent
    db --> parent
    fwd --> parent
    sentry --> parent
    otel --> parent
    dirsender --> parent
    core --> parent
    webapp --> parent

    basic --> api
    db --> api
    fwd --> api
    fwd --> basic
    sentry --> api
    otel --> api
    validation --> api
    validation --> basic
    dirsender --> core
    core --> api
    core --> db
    core --> fwd
    webapp --> core
    webapp --> fwd
    webapp --> sentry
    webapp --> otel
    webapp --> validation
    webapp --> dirsender

Loading

Straight lines mean "depends on".

Modules

phoss-ap-parent

The root POM. Acts as the BOM for all dependency version management (phase4, peppol-commons, peppol-reporting, ph-db, ph-commons, Spring Boot, PostgreSQL driver, MySQL driver, Flyway, etc.). All submodules inherit from this POM.

phoss-ap-api

Java interfaces, shared model classes, and enums. This is the contract layer that all other modules depend on.

Contains:

• IDocumentPayloadManager — interface for reading, writing, and deleting document files (implemented by phoss-ap-basic, accessible via APBasicMetaManager)
• IDocumentForwarder — interface for forwarding received documents to the Receiver Backend (implemented by phoss-ap-forwarding)
• IAPNotificationHandlerSPI — generic failure notification SPI (implemented by phoss-ap-sentry and phoss-ap-otel)
• IAPLifecycleEventSPI (since 0.9.0) — positive lifecycle event SPI (implemented by phoss-ap-otel) carrying throughput / latency observations for received, verified, forwarded, sent, MLS-correlated and scheduler-cycle events
• com.helger.phoss.ap.api.trace (since 0.9.0) — tracing facade (APTrace, IAPSpan, EAPSpanKind) and IAPTracerSPI (implemented by phoss-ap-otel via ServiceLoader). Allows in-tree code to record spans without depending on the OpenTelemetry API jar
• com.helger.phoss.ap.api.otel.CPhossAPOtel (since 0.9.0) — constants for the instrumentation scope, metric names, span names and attribute keys
• Retry strategy interface — customizable retry behavior (max attempts, backoff)
• Receiver check interface (IReceiverCheck or similar) — pluggable SPI for verifying that this AP services the addressed receiver participant
• Document verification interface (IDocumentVerifier or similar) — optional pluggable verification SPI for both outbound and inbound documents
• Domain model classes (transaction types, status enums, MLS codes, etc.)
• Callback interfaces (onSuccessfulAS4Sending, etc.)

Dependencies: Minimal — ph-commons only.

phoss-ap-basic

Basic implementations and utilities that build on the API layer. This module provides reusable building blocks that don't require database or framework dependencies.

Contains:

• DocumentPayloadManagerFileSystem — default implementation of IDocumentPayloadManager that stores documents as flat files on the local filesystem, organized by date/hour directories
• DocumentPayloadManagerS3 — alternative implementation of IDocumentPayloadManager that stores documents in Amazon S3, using s3://bucket/key URIs as opaque document paths
• APBasicMetaManager — singleton providing access to the document storage provider (selected via storage.mode configuration), identifier factory, and timestamp manager
• HTTP proxy configuration helper

Dependencies: phoss-ap-api, AWS SDK for S3.

No Spring dependencies in this module.

phoss-ap-db

Database access layer for PostgreSQL and MySQL using ph-db (JDBC wrapper).

Contains:

• Flyway migration scripts for PostgreSQL (under resources/db/migrate-postgresql/) and MySQL (under resources/db/migrate-mysql/)
• JDBC manager classes extending AbstractJDBCEnabledManager, one per table group:
  • OutboundTransactionManagerJDBC — CRUD for outbound_transaction and outbound_sending_attempt
  • InboundTransactionManagerJDBC — CRUD for inbound_transaction and inbound_forwarding_attempt
  • ArchivalManagerJDBC — move completed transactions to archive tables
• DB query logic using DBExecutor with ConstantPreparedStatementDataProvider for parameterized queries
• Flyway configuration class (similar to SMPFlywayConfiguration in phoss-smp)
• DataSource provider / JDBC configuration class

Dependencies: phoss-ap-api, ph-db-jdbc, PostgreSQL JDBC driver, MySQL JDBC driver, Flyway.

No Spring dependencies in this module.

phoss-ap-core

Core business logic and orchestration. This is the central module that ties together AS4 sending/receiving, DB operations, retry scheduling, MLS handling, and reporting.

Contains:

• Outbound orchestration: receive from API → store document to disk → record in DB → verify (optional) → send via phase4 → record attempt → trigger reporting
• Inbound orchestration: receive via phase4 servlet → duplicate check → receiver check → store document to disk → record in DB → verify (optional) → forward → record attempt → reporting
• MLS handling: generate MLS responses (as C3), receive and correlate MLS responses (as C2)
• Retry scheduler: periodic retry of failed outbound sends and failed inbound forwarding
• Archival scheduler: move completed transactions to archive tables
• Reporting integration: callbacks and peppol-reporting integration
• Notification dispatch: invoke generic notification interface on permanent failures
• Graceful shutdown logic

Dependencies: phoss-ap-api, phoss-ap-db, phase4-peppol-client, phase4-peppol-servlet, peppol-reporting, peppol-commons.

No Spring dependencies in this module.

phoss-ap-sentry

Optional Sentry error tracking integration. This module provides a notification handler that reports business-level failure events to Sentry with structured attributes.

Contains:

• APNotificationHandlerSentry — implementation of INotificationHandlerSPI that logs failure events (sending failures, forwarding failures, verification rejections, reporting failures) to Sentry

Dependencies: phoss-ap-api, io.sentry:sentry.

No Spring dependencies in this module. The Spring wiring (Logback appender registration, conditional activation via sentry.dsn) lives in phoss-ap-webapp.

phoss-ap-otel

Since 0.9.0. Optional OpenTelemetry integration. Provides an OTLP-first observability surface for the AP — metrics, traces and logs — without coupling the AP to any specific backend.

Contains:

• PhossAPTelemetry — static helper that exposes the phoss AP Meter and caches the registered counter / histogram instruments
• APNotificationHandlerOtel — implementation of IAPNotificationHandlerSPI that translates AP failure callbacks into OTel counter increments and span events
• APLifecycleEventHandlerOtel — implementation of IAPLifecycleEventSPI that translates positive lifecycle events into OTel counters and histograms (throughput, SLA durations, scheduler cycles)
• OtelAPTracerSPI + OtelAPSpan — implementation of the IAPTracerSPI abstraction from phoss-ap-api, registered via META-INF/services so manual spans created through APTrace flow into the global OpenTelemetry instance

The tracing constants (CPhossAPOtel) and trace abstraction (APTrace, IAPSpan, EAPSpanKind, IAPTracerSPI) live in phoss-ap-api so other modules can record spans without depending on the OpenTelemetry API jar.

Dependencies: phoss-ap-api, io.opentelemetry:opentelemetry-api, io.opentelemetry:opentelemetry-sdk, io.opentelemetry:opentelemetry-sdk-extension-autoconfigure, io.opentelemetry:opentelemetry-exporter-otlp, io.opentelemetry.instrumentation:opentelemetry-instrumentation-annotations.

No Spring dependencies in this module. The Spring wiring (SDK autoconfigure bootstrap, conditional activation via otel.enabled, registration of both notification and lifecycle handlers) lives in phoss-ap-webapp. See OpenTelemetry Integration for runtime configuration.

phoss-ap-validation

Optional module providing document verification via the phorm Validation Service. Implements both IInboundDocumentVerifierSPI and IOutboundDocumentVerifierSPI in a single shared class (PhormDocumentVerifier).

Contains:

• PhormDocumentVerifier — calls the phorm Validation Service's /api/dd_and_validate/ endpoint, parses the phive JSON response, and rejects documents that contain at least one phive ERROR
• PhiveToMlsMapper — converts a phive ValidationResultList to a detailed MlsOutcome for inbound rejections (see Message Level Status#verifier-driven-issue-mapping-since-v0100)
• ServiceLoader registration files for both inbound and outbound verifier SPIs

Dependencies: phoss-ap-api, phoss-ap-basic, ph-httpclient, ph-json, phive-result.

No Spring dependencies in this module.

phoss-ap-dirsender

Optional directory-based batch sender for pre-built SBD files. Watches a configurable directory for *.xml files, submits each via the existing outbound pipeline (OutboundOrchestrator), and moves processed files to success/ or error/ subdirectories with accompanying JSON result files. Disabled by default.

Contains:

• DirectorySenderScheduler — timer lifecycle (start/stop), startup recovery of files stuck in pending/
• DirectoryScanTask — periodic scan for new files + cleanup of pending files that reached a final DB state
• DirectoryFileProcessor — single-file processing: move to pending/, submit SBD, send via AS4, move to success/ or error/
• APDirSenderConfig — configuration accessor for dirsender.* properties

Dependencies: phoss-ap-core.

No Spring dependencies in this module.

phoss-ap-forwarding

All forwarding implementations in a single module. The active forwarding mode is selected at runtime via the forwarding.mode configuration property.

Contains:

• HTTP POST forwarder (async reporting variant) — posts SBD to configured endpoint
• HTTP POST forwarder (sync reporting variant) — posts SBD, reads C4 country code from response
• S3 uploader — stores the SBD in a configured S3 bucket
• SFTP uploader — uploads the SBD to a configured SFTP server using ph-jsch abstractions
• Filesystem writer — writes the SBD to a local directory

Dependencies: phoss-ap-api, phoss-ap-basic, Apache HttpClient, AWS SDK for S3, ph-jsch (com.helger.web:ph-jsch).

No Spring dependencies in this module.

phoss-ap-webapp

The Spring Boot application that assembles everything into a runnable deployment. This is the only module that depends on Spring.

Contains:

• Spring Boot application entry point
• REST controllers (outbound submit, status queries, inbound reporting API)
• AS4 servlet configuration (phase4 Peppol servlet registration)
• Application configuration (application.properties)
• Security / authentication (API token handling)
• Wiring: connects Spring Boot to the non-Spring core via dependency injection of manager instances

Dependencies: phoss-ap-core, phoss-ap-forwarding, phoss-ap-sentry, phoss-ap-otel, Spring Boot.

phoss-ap-extension-demo

Since 0.10.4. Example module — not part of a standard deployment. A minimal, runnable example of the Runtime Extensions mechanism. It demonstrates how a third party packages custom SPI implementations into a thin jar that is loaded from the /ext directory at runtime (via Spring Boot's PropertiesLauncher / LOADER_PATH), without rebuilding the application.

Contains:

• DemoLifecycleEventSPI — logging-only implementation of IAPLifecycleEventSPI
• DemoNotificationHandlerSPI — logging-only implementation of IAPNotificationHandlerSPI
• META-INF/services registrations for both SPIs
• An example Dockerfile that bakes the extension into a derived phoss-ap image, plus assemble.sh (build the jar + image) and run-docker-ph.sh (run it locally) helper scripts

Dependencies: phoss-ap-api with scope provided — so the produced jar bundles nothing the AP already ships and stays thin.

No Spring dependencies in this module. It is intentionally not referenced by phoss-ap-webapp; extensions are added at deployment time, not baked into the application.

Deployment Assembly

A deployment includes:

phoss-ap-parent
  └── phoss-ap-api
  └── phoss-ap-basic
  └── phoss-ap-db
  └── phoss-ap-forwarding
  └── phoss-ap-dirsender
  └── phoss-ap-sentry
  └── phoss-ap-otel
  └── phoss-ap-validation
  └── phoss-ap-core
  └── phoss-ap-webapp

The phoss-ap-extension-demo module is not part of a deployment — it is an example of the Runtime Extensions mechanism that is loaded from the /ext directory at runtime.

All forwarding implementations are included in the single phoss-ap-forwarding module. The active forwarding mode is selected at runtime via the forwarding.mode configuration property.