The 3-layer architecture

Elmar.tax is built as three layers that stack on top of each other. Each layer is independently usable, but most teams only need the top one.

Layer 3 — Recommended for most teams
Elmar REST Service

      REST API wrapping the layers below. Accepts JSON or XML.
      Runs as a Docker container inside your infrastructure.
      Exposes each tax form as a dedicated endpoint.
    
Layer 2 — Java teams
elster-databinding

      Type-safe Java models generated from ELSTER XSDs.
      Uniform factory pattern: TransferHeader → NutzdatenHeader → Nutzdatenblock → DatenTeil → ElsterForm.
      One Maven module per form/year for clean version isolation.
    
Layer 1 — Java teams, advanced
eric-wrapper-sdk

      Java wrapper around ERiC using Project Panama (Foreign Function & Memory API, JDK 24+).
      No JNI. Concurrency-safe access to ERiC's single-threaded core.
      Cross-platform: Linux (x64) and macOS (universal).
    
Foundation — provided by German tax authorities
ERiC (ELSTER Rich Client)

      Official native C library for secure tax data exchange with ELSTER servers.
      Single-threaded. Bundled inside the Elmar Docker image.
    

How it fits together

ERiC (bottom) is the official C library from German tax authorities. It handles encryption, TLS, and communication with ELSTER servers. It is single-threaded and expects to be called from a single thread.
eric-wrapper-sdk wraps ERiC using jextract-generated Panama bindings. It provides EricFacade — a Java-idiomatic interface that serializes concurrent access, manages certificates, and maps native error codes to Java exceptions.
elster-databinding generates JAXB classes from official ELSTER XSDs and provides a factory per form/year. Each factory builds the complete ELSTER envelope: TransferHeader + NutzdatenHeader + Nutzdatenblock + DatenTeil = ElsterForm.
Elmar REST (top) is a Spring Boot Kotlin application that wires everything together. It accepts TaxDeclaration payloads via HTTP, converts them to ELSTER envelopes, and submits them through ERiC. It returns ERiC's response transparently — no additional validation layer.

Concurrency model

ERiC is single-threaded. Elmar handles this transparently:

REST calls are serialized internally — concurrent requests block until the current ERiC exchange completes
This is safe and correct for typical middleware workloads
For high-concurrency peaks (e.g., monthly submission deadlines), integrate Elmar behind a work queue on your side
Async processing and built-in queueing are on the roadmap

Operational model

One certificate per running instance — each container is configured with a single ELSTER certificate
Synchronous processing — request in, response out, no background jobs
No built-in authentication — Elmar is designed as an internal service, behind your own API gateway or network boundary
Docker-first — Linux and macOS supported; Windows works when running via container

Compliance and licensing

Due to ERiC licensing and regulatory constraints, Elmar.tax is designed to run entirely within customer infrastructure and must not be used as a SaaS or portal solution (Portallösung).

This is a fundamental design decision, not a limitation — it ensures you stay compliant with German tax authority regulations while maintaining full control over your data and certificates.