# oviva-ag/epa4all-client architecture

> Architecture diagram of the GitHub repository oviva-ag/epa4all-client, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oviva-ag/epa4all-client
- Repository: https://github.com/oviva-ag/epa4all-client

## Overview

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`](https://github.com/oviva-ag/epa4all-client/tree/main/epa4all-client) (Client API), [`konnektor/konnektor-client`](https://github.com/oviva-ag/epa4all-client/tree/main/konnektor/konnektor-client) (Konnektor client), [`vau/vau-httpclient`](https://github.com/oviva-ag/epa4all-client/tree/main/vau/vau-httpclient) (VAU HTTP), [`epa4all-client/src/main/java/com/oviva/telematik/epa4all/client/internal/Epa4AllClientImpl.java`](https://github.com/oviva-ag/epa4all-client/blob/main/epa4all-client/src/main/java/com/oviva/telematik/epa4all/client/internal/Epa4AllClientImpl.java) (Client impl)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Repository"]
  node_repo["epa4all-client<br/>maven multi-module"]
end

subgraph group_client["Client layer"]
  node_rest_service["REST service<br/>http facade"]
  node_client_api["Client API<br/>orchestration library"]
  node_client_factory["Factory builder<br/>wiring api"]
  node_client_impl["Client impl<br/>workflow engine"]
  node_client_ssl["SSL setup<br/>security setup"]
  node_client_trust["Trust roots<br/>trust material"]
  node_phr_client["PHR client<br/>soap boundary"]
  node_phr_service["PhrService<br/>soap orchestration<br/>[PhrService.java]"]
  node_phr_factory["SOAP factory<br/>ws client setup"]
  node_phr_mtom["MTOM binding<br/>xml binding"]
end

subgraph group_infrastructure["Integration layer"]
  node_vau_auth["VAU authz<br/>authorization client"]
  node_vau_http["VAU HTTP<br/>secure transport"]
  node_vau_lib["VAU lib<br/>protocol core"]
  node_vau_proxy["VAU proxy<br/>proxy process"]
  node_konn_service["Konnektor client<br/>connector client"]
  node_konn_bindings["SOAP bindings<br/>generated ws api"]
  node_tsl_tooling["TSL tooling<br/>trust utility"]
end

node_repo -->|"contains"| node_rest_service
node_repo -->|"contains"| node_client_api
node_repo -->|"contains"| node_phr_client
node_repo -->|"contains"| node_vau_auth
node_repo -->|"contains"| node_konn_service
node_repo -->|"contains"| node_vau_http
node_repo -->|"contains"| node_vau_lib
node_repo -->|"contains"| node_vau_proxy
node_repo -->|"contains"| node_tsl_tooling
node_rest_service -->|"calls"| node_client_api
node_client_api -->|"built by"| node_client_factory
node_client_api -->|"implemented by"| node_client_impl
node_client_impl -->|"loads"| node_client_ssl
node_client_ssl -->|"uses"| node_client_trust
node_client_impl -->|"delegates to"| node_phr_service
node_phr_service -->|"configured by"| node_phr_factory
node_phr_service -->|"encodes"| node_phr_mtom
node_client_api -->|"uses"| node_konn_service
node_client_api -->|"uses"| node_vau_auth
node_vau_auth -->|"runs over"| node_vau_http
node_vau_http -->|"implements"| node_vau_lib
node_vau_http -->|"validates against"| node_tsl_tooling
node_vau_proxy -->|"routes through"| node_vau_lib
node_konn_service -->|"wraps"| node_konn_bindings
node_konn_service -->|"uses"| node_client_ssl
node_konn_service -->|"depends on"| node_tsl_tooling

click node_rest_service "https://github.com/oviva-ag/epa4all-client/tree/main/epa4all-rest-service"
click node_client_api "https://github.com/oviva-ag/epa4all-client/tree/main/epa4all-client"
click node_client_factory "https://github.com/oviva-ag/epa4all-client/blob/main/epa4all-client/src/main/java/com/oviva/telematik/epa4all/client/Epa4AllClientFactoryBuilder.java"
click node_client_impl "https://github.com/oviva-ag/epa4all-client/blob/main/epa4all-client/src/main/java/com/oviva/telematik/epa4all/client/internal/Epa4AllClientImpl.java"
click node_client_ssl "https://github.com/oviva-ag/epa4all-client/blob/main/epa4all-client/src/main/java/com/oviva/telematik/epa4all/client/internal/SslContextBuilder.java"
click node_client_trust "https://github.com/oviva-ag/epa4all-client/blob/main/epa4all-client/src/main/java/com/oviva/telematik/epa4all/client/internal/TelematikTrustRoots.java"
click node_phr_client "https://github.com/oviva-ag/epa4all-client/tree/main/epa4all-phr-client"
click node_phr_service "https://github.com/oviva-ag/epa4all-client/blob/main/epa4all-phr-client/src/main/java/com/oviva/telematik/epaapi/PhrService.java"
click node_phr_factory "https://github.com/oviva-ag/epa4all-client/blob/main/epa4all-phr-client/src/main/java/com/oviva/telematik/epaapi/SoapClientFactory.java"
click node_phr_mtom "https://github.com/oviva-ag/epa4all-client/blob/main/epa4all-phr-client/src/main/java/com/oviva/telematik/epaapi/internal/MtomConfigOutInterceptor.java"
click node_vau_auth "https://github.com/oviva-ag/epa4all-client/tree/main/epa4all-vau-client"
click node_vau_http "https://github.com/oviva-ag/epa4all-client/tree/main/vau/vau-httpclient"
click node_vau_lib "https://github.com/oviva-ag/epa4all-client/tree/main/vau/vau-lib"
click node_vau_proxy "https://github.com/oviva-ag/epa4all-client/tree/main/vau/vau-proxy-server"
click node_konn_service "https://github.com/oviva-ag/epa4all-client/tree/main/konnektor/konnektor-client"
click node_konn_bindings "https://github.com/oviva-ag/epa4all-client/tree/main/konnektor/epa-fm-api"
click node_tsl_tooling "https://github.com/oviva-ag/epa4all-client/tree/main/telematik-tsl"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_repo toneBlue
class node_rest_service,node_client_api,node_client_factory,node_client_impl,node_client_ssl,node_client_trust,node_phr_client,node_phr_service,node_phr_factory,node_phr_mtom toneAmber
class node_vau_auth,node_vau_http,node_vau_lib,node_vau_proxy,node_konn_service,node_konn_bindings,node_tsl_tooling toneMint
```

## Components

### Repository

Top-level Maven multi-module ePA client stack

- **epa4all-client**: maven multi-module · Top-level repository coordinating the ePA client stack

### Client layer

Library-first orchestration and REST façade

- [REST service](https://github.com/oviva-ag/epa4all-client/tree/main/epa4all-rest-service): http facade · Thin OpenAPI-facing wrapper around the client workflow · `epa4all-rest-service`
- [Client API](https://github.com/oviva-ag/epa4all-client/tree/main/epa4all-client): orchestration library · Public Epa4AllClient boundary for document workflows · `epa4all-client`
- [Factory builder](https://github.com/oviva-ag/epa4all-client/blob/main/epa4all-client/src/main/java/com/oviva/telematik/epa4all/client/Epa4AllClientFactoryBuilder.java): wiring api · Builds the client with environment, proxy, and Konnektor wiring · `epa4all-client/src/main/java/com/oviva/telematik/epa4all/client/Epa4AllClientFactoryBuilder.java`
- [Client impl](https://github.com/oviva-ag/epa4all-client/blob/main/epa4all-client/src/main/java/com/oviva/telematik/epa4all/client/internal/Epa4AllClientImpl.java): workflow engine · Implements submission flow, URI rewriting, logging, and exception mapping · `epa4all-client/src/main/java/com/oviva/telematik/epa4all/client/internal/Epa4AllClientImpl.java`
- [SSL setup](https://github.com/oviva-ag/epa4all-client/blob/main/epa4all-client/src/main/java/com/oviva/telematik/epa4all/client/internal/SslContextBuilder.java): security 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](https://github.com/oviva-ag/epa4all-client/blob/main/epa4all-client/src/main/java/com/oviva/telematik/epa4all/client/internal/TelematikTrustRoots.java): trust material · Bundled truststores and Telematik root handling · `epa4all-client/src/main/java/com/oviva/telematik/epa4all/client/internal/TelematikTrustRoots.java`
- [PHR client](https://github.com/oviva-ag/epa4all-client/tree/main/epa4all-phr-client): soap boundary · PHR and XDS document service boundary with bindings and MTOM support · `epa4all-phr-client`
- [PhrService](https://github.com/oviva-ag/epa4all-client/blob/main/epa4all-phr-client/src/main/java/com/oviva/telematik/epaapi/PhrService.java): soap orchestration · Wraps PHR service calls and maps document-level failures · `epa4all-phr-client/src/main/java/com/oviva/telematik/epaapi/PhrService.java`
- [SOAP factory](https://github.com/oviva-ag/epa4all-client/blob/main/epa4all-phr-client/src/main/java/com/oviva/telematik/epaapi/SoapClientFactory.java): ws client setup · Creates configured SOAP clients and interceptors · `epa4all-phr-client/src/main/java/com/oviva/telematik/epaapi/SoapClientFactory.java`
- [MTOM binding](https://github.com/oviva-ag/epa4all-client/blob/main/epa4all-phr-client/src/main/java/com/oviva/telematik/epaapi/internal/MtomConfigOutInterceptor.java): xml 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](https://github.com/oviva-ag/epa4all-client/tree/main/epa4all-vau-client): authorization client · Challenge, attestation, signing, and OIDC-style auth flows · `epa4all-vau-client`
- [VAU HTTP](https://github.com/oviva-ag/epa4all-client/tree/main/vau/vau-httpclient): secure transport · HTTP client layered with VAU handshake, trust validation, and logging · `vau/vau-httpclient`
- [VAU lib](https://github.com/oviva-ag/epa4all-client/tree/main/vau/vau-lib): protocol core · VAU state machine and crypto primitives · `vau/vau-lib`
- [VAU proxy](https://github.com/oviva-ag/epa4all-client/tree/main/vau/vau-proxy-server): proxy process · Proxy used to route traffic through VAU or VPN-backed setups · `vau/vau-proxy-server`
- [Konnektor client](https://github.com/oviva-ag/epa4all-client/tree/main/konnektor/konnektor-client): connector client · High-level wrapper over connector SOAP APIs · `konnektor/konnektor-client`
- [SOAP bindings](https://github.com/oviva-ag/epa4all-client/tree/main/konnektor/epa-fm-api): generated ws api · Generated connector interfaces and schemas for official services · `konnektor/epa-fm-api`
- [TSL tooling](https://github.com/oviva-ag/epa4all-client/tree/main/telematik-tsl): trust utility · Downloads Telematik TSL and CA root material · `telematik-tsl`

## Connections

- 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
