Architecture Overview

Architecture Overview

phoss-ap is an open-source Peppol Access Point built on phase4 and Spring Boot.

Key Components

Component	Technology	Purpose
AS4 Engine	phase4	AS4 message sending and receiving
Database	PostgreSQL	Persistent storage of transactions, metadata, and reporting data
API	Spring Boot REST	Inbound API for triggering sends and reporting
Forwarding	Pluggable (per instance)	Delivering received documents to the Receiver Backend
Retry	Customizable Java interfaces	Automatic retry of failed sends and failed forwarding
Notifications	Generic Java interface	Alerting on permanent failures
Reporting	peppol-reporting	Peppol TSR/EUSR generation

Peppol 4-Corner Model Context

C1 (Sender) --> C2 (Sender AP) --> C3 (Receiver AP) --> C4 (Receiver)

phoss-ap operates exclusively on the C2-to-C3 boundary. It does not implement C1 or C4 functionality. The systems that interact with the AP on either side are:

• Sender Backend: An internal system within C2 that submits documents to the AP for outbound transmission.
• Receiver Backend: An internal system within C3 that receives documents from the AP after inbound reception.

[Sender Backend] --> [phoss-ap (C2)] --AS4--> [Remote AP (C3)]
[Remote AP (C2)] --AS4--> [phoss-ap (C3)] --> [Receiver Backend]

Sending Input Modes

The AP accepts outbound documents from the Sender Backend via its API in two forms:

1. Raw business document + metadata: The AP creates the SBDH envelope. The Sender Backend provides sender ID, receiver ID, document type ID, process ID, and C1 country code as API parameters.
2. Pre-built SBD: The Sender Backend provides a complete Standard Business Document (with SBDH). All metadata (including C1 country code) is extracted from the SBDH.

Receiving Forwarding Modes

Received documents are forwarded to the Receiver Backend. The forwarding mode is configured per AP instance (one mode per deployment):

1. HTTP POST (async reporting): Document is POSTed to the Receiver Backend. The Receiver Backend calls the reporting API asynchronously later.
2. HTTP POST (sync reporting): Document is POSTed to the Receiver Backend. The Receiver Backend responds synchronously with the C4 country code, and the AP triggers reporting immediately.
3. S3 + link forwarding: Document is stored in S3, and a link/reference is forwarded to the Receiver Backend. Reporting is asynchronous.
4. SFTP: Document is uploaded via SFTP. Reporting is asynchronous.

Duplicate Detection

AS4 duplicate detection is configurable:

• Reject: Duplicate messages (same AS4 Message ID) are rejected at the AS4 level.
• Store and flag: Duplicates are stored in the DB but flagged as duplicates.

Archival

Transactions that are fully completed successfully are moved from the primary DB tables to backup/archive tables to prevent table bloat. Failed transactions remain in the primary tables.

Graceful Shutdown

On shutdown, the AP:

1. Stops accepting new inbound AS4 messages and new outbound API submissions.
2. Finalizes any messages currently being processed (in-flight AS4 sends and forwarding operations).

This ensures no transactions are left in an inconsistent state.

Forwarding Payload

The AP forwards the complete SBD (Standard Business Document = SBDH + business document) to the Receiver Backend. The Receiver Backend is responsible for parsing the SBDH and extracting the business document if needed.

Notifications

A generic Java interface is provided for failure notifications. Concrete implementations are deployment-specific (e.g., email, Slack, monitoring system webhook). Notification triggers include:

• Permanent sending failure (max retries exhausted)
• Permanent forwarding failure on the receiving side