Once-Only Simulation

2025 · Active

An X-Road topology you can run in a terminal

Scala 3sbtX-RoadOnce-Only Principle

The problem

The once-only principle — that citizens should hand the state a piece of information once, not to every authority separately — is easy to state and hard to picture. Discussions about it in Germany stall on an intuition that it must mean a giant central register, which is precisely what Estonia's X-Road does not do. Explaining the difference in prose or on a slide rarely lands. A running system that anyone can drive from a terminal makes the distinction concrete: you watch the query travel between authorities, and you watch the log entry appear on the citizen's side.

Architecture

Federated authorities, no central register

A central server holds only the service registry and configuration — which authority offers which service, and how to reach it. The data itself never leaves the authority that owns it. Four simulated authorities participate: the Munich police, the residents' registration office, the vehicle licensing office and the citizen portal. Each sits behind its own security server (SS-POLIZEI, SS-EMA, SS-KFZ, SS-PORTAL), mirroring how X-Road actually separates the member from the network.

A concrete scenario rather than an abstract demo

The simulation walks through a parking ticket. The police record a licence plate, then make two queries across the network: the vehicle licensing office answers who the keeper is, and the residents' registration office answers where that person currently lives. The ticket can be issued. Nothing was copied into a central database, and neither authority had to know in advance who would ask.

Transparency as a first-class component

Both queries land in a log the citizen can inspect through the portal. This is the part that usually gets left out of once-only demonstrations, and it is the part that makes the model politically defensible: data sovereignty stays with the authority holding the record, and accountability stays with the person the record is about.

Scala 3 and a single fat JAR

The whole thing builds to one assembly JAR and runs on any Java 17 runtime. No containers, no orchestration, no cloud account — the point is that someone can clone it and see the mechanism in under a minute.

Decisions

Terminal application over a web UIInteractive CLI: A browser interface would have pulled attention towards the front end, which is not what the project is about. In a terminal the message flow between authorities is the only thing on screen.
Simulated security servers instead of real X-RoadA simplified reimplementation of the topology: Running genuine X-Road nodes needs certificates, a trust federation and considerable operational work. Reproducing the topology and the message flow captures what the audience needs to understand, and the simplification is stated rather than hidden.
Scala over PythonScala 3 on the JVM: Modelling authorities, services and messages as an algebraic data type makes illegal states hard to construct, which matters when the point of the exercise is that the protocol is well defined.

Installation

Java 17 and sbt are the only prerequisites:

sbt assembly
java -jar target/scala-3.7.0/once-only-simulation.jar

Why Estonia keeps coming up

This grew out of my bachelor's thesis on Estonia's digital governance system and whether it transfers to German administrative processes. The short answer is that the hard part is not the technology — X-Road is a message bus with good discipline about identity and logging, and none of it is exotic. The hard part is the organisational precondition: every authority has to accept that it remains the owner of its own data and answers queries about it, rather than shipping copies into someone else's system. This simulation isolates the technical half so the organisational half can be discussed on its own terms.

All projects