How oviva-ag/epa4all-client works
1. What this repo is
This is a multi-module Java/Maven repository for the German ePA 3.0 ecosystem. It provides a reusable document client, a thin REST adapter, Konnektor/SOAP integrations, VAU transport/security components, and trust-list tooling. The architecture is library-first, with one small service wrapper on top.
2. Top-level module boundaries
- epa4all-client: main orchestration library for document workflows.
- epa4all-rest-service: HTTP/OpenAPI facade around the client.
- epa4all-phr-client: PHR/XDS SOAP client layer.
- epa4all-vau-client: authorization and VAU-related client logic.
- konnektor/*: connectivity to the eHealth Konnektor and its SOAP APIs.
- vau/*: reusable VAU protocol/HTTP client and a proxy server.
- telematik-tsl: utilities for downloading Telematik trust roots / TSL material.
3. Primary data flow
The main business flow is document submission:
external caller → epa4all-rest-service → epa4all-client → Konnektor/PHR/VAU infrastructure → ePA backend services.
The REST service only adapts requests and responses; the actual workflow logic lives in the client modules.
4. epa4all-client as the orchestration boundary
This module exposes the public Epa4AllClient API and a FactoryBuilder for wiring it up with environment, Konnektor proxy address, and a KonnektorService. Internally it manages SSL context setup, trust roots, URI rewriting, logging, and domain-specific exceptions such as authorization or duplicate-document failures.
5. PHR/SOAP service layer
epa4all-phr-client encapsulates the PHR service and XDS document service contracts. It contains WSDL/XSD resources and JAXB/JAX-WS binding customizations, plus an MTOM interceptor for binary payloads. This is the boundary where document content is turned into the SOAP/XML shapes expected by the ePA infrastructure.
6. Konnektor integration layer
The konnektor subtree is the client side of the Telematik Konnektor ecosystem.
- epa-fm-api holds generated SOAP bindings and schemas for the official connector interfaces.
- konnektor-client wraps those bindings into higher-level services like card, certificate, auth signature, and event handling, plus connection management and certificate/XML utilities.
This layer is the bridge to the physical or hosted Konnektor instance.
7. VAU stack
The vau subtree is split into:
- vau-lib: protocol/state-machine and crypto primitives for VAU message exchange.
- vau-httpclient: an HTTP client implementation layered with VAU handshake, trust validation, logging, and certificate handling.
- vau-proxy-server: a lightweight proxy process used to route traffic through the VAU channel or into VPN-backed network setups.
This is the main security/transport boundary around requests to telematics infrastructure.
8. Authorization and identity flows
epa4all-vau-client handles authorization-related concerns, including challenge response, attestation, signing, JOSE/Brainpool crypto, and OIDC-style client interactions. It separates authz concerns from document transport, which is important for diagramming because identity proofing and message delivery are distinct subsystems here.
9. Trust and certificate material
Trust is treated as a first-class architectural concern. The repo includes bundled truststores, Telematik TSL-related download utilities, and certificate/CA validation code in the VAU HTTP client and Konnektor client. This supports the strict certificate chain and trust-root requirements of the ePA/TI environment.
10. Runtime/deployment shape
The REST service is designed to run as a container and can be deployed either with direct Konnektor access or through a sidecar-style VPN/proxy setup. The README explicitly shows a Docker-based deployment and a userspace WireGuard pattern, which affects the network boundary in any architecture diagram.
11. Service façade characteristics
epa4all-rest-service is intentionally thin: it exposes OpenAPI-described endpoints, reads configuration from the environment, loads credentials from a PKCS#12 store, and maps domain exceptions to HTTP responses. It also configures JSON logging, which suggests it is meant to be the operational entry point for external systems.
12. Build and validation structure
The repo is organized as a Maven multi-module build with strong test coverage across modules, including unit tests and end-to-end tests for client/proxy/service behavior. GitHub Actions handle unit tests, formatting, releases, and issue notifications, but those are support concerns rather than core runtime architecture.
Main entry points: epa4all-client Client API · konnektor-client Konnektor client · vau-httpclient VAU HTTP · Epa4AllClientImpl.java Client impl
Components 18
Repository
Top-level Maven multi-module ePA client stack
- epa4all-client · Top-level repository coordinating the ePA client stack
Client layer
Library-first orchestration and REST façade
- REST service · Thin OpenAPI-facing wrapper around the client workflow
epa4all-rest-service - Client API · Public Epa4AllClient boundary for document workflows
epa4all-client - Factory builder · Builds the client with environment, proxy, and Konnektor wiring
epa4all-client/src/main/java/com/oviva/telematik/epa4all/client/Epa4AllClientFactoryBuilder.java - Client impl · Implements submission flow, URI rewriting, logging, and exception mapping
epa4all-client/src/main/java/com/oviva/telematik/epa4all/client/internal/Epa4AllClientImpl.java - SSL setup · Prepares SSL context and trust-root loading for client calls
epa4all-client/src/main/java/com/oviva/telematik/epa4all/client/internal/SslContextBuilder.java - Trust roots · Bundled truststores and Telematik root handling
epa4all-client/src/main/java/com/oviva/telematik/epa4all/client/internal/TelematikTrustRoots.java - PHR client · PHR and XDS document service boundary with bindings and MTOM support
epa4all-phr-client - PhrService · Wraps PHR service calls and maps document-level failures
epa4all-phr-client/src/main/java/com/oviva/telematik/epaapi/PhrService.java - SOAP factory · Creates configured SOAP clients and interceptors
epa4all-phr-client/src/main/java/com/oviva/telematik/epaapi/SoapClientFactory.java - MTOM binding · Handles binary payload transport and SOAP/XML customization
epa4all-phr-client/src/main/java/com/oviva/telematik/epaapi/internal/MtomConfigOutInterceptor.java
Integration layer
Konnektor, VAU, and trust infrastructure
- VAU authz · Challenge, attestation, signing, and OIDC-style auth flows
epa4all-vau-client - VAU HTTP · HTTP client layered with VAU handshake, trust validation, and logging
vau/vau-httpclient - VAU lib · VAU state machine and crypto primitives
vau/vau-lib - VAU proxy · Proxy used to route traffic through VAU or VPN-backed setups
vau/vau-proxy-server - Konnektor client · High-level wrapper over connector SOAP APIs
konnektor/konnektor-client - SOAP bindings · Generated connector interfaces and schemas for official services
konnektor/epa-fm-api - TSL tooling · Downloads Telematik TSL and CA root material
telematik-tsl
Connections 26
- epa4all-client → REST service: contains · Top-level build includes the HTTP façade module
- epa4all-client → Client API: contains · Top-level build includes the orchestration library
- epa4all-client → PHR client: contains · Top-level build includes the SOAP document client module
- epa4all-client → VAU authz: contains · Top-level build includes authorization logic
- epa4all-client → Konnektor client: contains · Top-level build includes Konnektor integration
- epa4all-client → VAU HTTP: contains · Top-level build includes VAU transport module
- epa4all-client → VAU lib: contains · Top-level build includes VAU protocol core
- epa4all-client → VAU proxy: contains · Top-level build includes proxy server module
- epa4all-client → TSL tooling: contains · Top-level build includes trust-list tooling
- REST service → Client API: calls · REST endpoints adapt requests into the client workflow
- Client API → Factory builder: built by · Factory builder wires the public client API
- Client API → Client impl: implemented by · Core workflow implementation lives in the internal client class
- Client impl → SSL setup: loads · Client implementation prepares SSL context and trust roots
- SSL setup → Trust roots: uses · Trust-root material feeds SSL initialization
- Client impl → PhrService: delegates to · Document workflow reaches the SOAP service boundary
- PhrService → SOAP factory: configured by · SOAP service uses a dedicated client factory
- PhrService → MTOM binding: encodes · Binary document payloads are handled via MTOM binding
- Client API → Konnektor client: uses · Main orchestration depends on Konnektor services
- Client API → VAU authz: uses · Authorization-related flows are separated into VAU auth client
- VAU authz → VAU HTTP: runs over · Auth flows rely on the secure VAU HTTP transport
- VAU HTTP → VAU lib: implements · HTTP client layers on the VAU protocol core
- VAU HTTP → TSL tooling: validates against · Trust validation depends on Telematik root material
- VAU proxy → VAU lib: routes through · Proxy process participates in VAU channel handling
- Konnektor client → SOAP bindings: wraps · Service layer wraps generated SOAP bindings
- Konnektor client → SSL setup: uses · Connector communications rely on TLS and trust setup
- Konnektor client → TSL tooling: depends on · Connector trust and certificate handling align with TSL material