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]
    validation[phoss-ap-validation]
    core[phoss-ap-core]
    webapp[phoss-ap-webapp]

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

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

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, 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)
• Notification interface — generic failure notification SPI
• 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 using ph-db (JDBC wrapper).

Contains:

• Flyway migration scripts for PostgreSQL (under resources/db/migrate-postgresql/)
• 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, 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-validation

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

Contains:

• ValidationServiceDocumentVerifier — calls the phorm Validation Service's /api/dd_and_validate/ endpoint, parses the phive JSON response, and rejects documents with INVALID overall conformance
• 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-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

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, Spring Boot.

Deployment Assembly

A deployment includes:

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

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.