Repository navigation
Domain Model
The database is storage. The API mirrors domains and features, never tables. There is no one-to-one resource per table or view, and no storage column name ever appears in a public payload. This page describes the model the API speaks. The logical read model underneath it, entity by entity and field by field, is the Data Model; each bounded context below has a data-model page of its own (Places, Roads, Energy, Parking, Transit, Accessibility, Weather, Provenance).
| Bounded context | The client's language | Aggregates (root in bold) | Value objects |
|---|---|---|---|
| Places (used by all others) | "Where is X, what is here?" | Place, Address, PointOfInterest |
PlaceId, GeoPoint, Area (circle, bounding box, corridor), AdminRegion, PlaceKind
|
| Road conditions | "How is the A8 Munich–Stuttgart? What is ahead?" | Corridor (a motorway and direction, or a client route plus a buffer), RoadSituation (closure, roadworks, jam, hazard, restriction) |
RoadRef, Direction, RoadPosition (km, junction), Severity, Lamp (green, amber, red), TimeWindow
|
| Energy stops | "Refuel or charge near X or along the route" |
FuelStop with FuelOffer[], ChargingSite with ChargePoint[]
|
FuelProduct (hydrogen included), Price (fixed point, never floating point), PowerKw, ConnectorType, Availability with observation time |
| Parking | "Park (a lorry) near X or along the route" | ParkingSite, SharingStation |
Occupancy (free, capacity, trend), VehicleClass
|
| Public transport | "Next departures and disruptions at Köln Hbf" | StopPlace, Departure, Disruption |
StopPlaceId, Line, Mode, planned and expected time, Platform
|
| Accessibility | "Do the lifts work?" | StationAccessibility |
Facility, FacilityState, StepFreeAccess
|
| Weather risk | "Weather risk at X or along the route" | WeatherRisk |
Warning (hazard, level 1–4, validity), RoadWeather
|
| Driving rules | "Rules for lorries on Sunday" | RuleTopic |
RuleText, ReviewedOn
|
| Provenance (shared kernel) | "Who says so, and may I use it?" | attached to every result |
SourceFamily, Attribution, Licence, ConditionNote, PurposeNote, AsOf
|
| Access (the API's own) | Keys, plans, usage | ApiKey, Plan, UsageLedger |
KeyId, Scope, Tier, UseClass (consumer, non-commercial, commercial), Quota
|
flowchart TD
Places[Places] --> Roads[Road conditions]
Places --> Energy[Energy stops]
Places --> Parking[Parking]
Places --> Transit[Public transport]
Places --> Weather[Weather risk]
Transit --> Access11y[Accessibility]
Prov[(Provenance<br/>shared kernel)] -.attached to.-> Roads & Energy & Parking & Transit & Weather & Access11y & Places
Access[Access<br/>keys, plans, gate] -.filters by source family.-> Prov
- Places resolves first for every feature: a text, an id or a coordinate becomes a place or an area.
- Provenance is a shared kernel: every result carries it.
- Access never sees domain objects. It decides only which source families a request may read.
-
Time: instants are stored and sent in UTC (
2026-11-01T13:05:00Z); where people read them, a…Localcompanion gives the Europe/Berlin rendering with its offset (2026-11-01T14:05:00+01:00). See Spec: Scope, Conventions and References and ADR-0004. -
Units: metres for distance (
distanceM), kilowatts for power; motorway chainage is the road's own kilometre marking (fromKm). Prices are fixed-point decimal strings with a currency, never floating point. -
Bounded areas: every
Area(radius, bounding box, corridor buffer, route length) has a configured maximum. -
Unknown codes are safe: a storage code the API does not know becomes
kind: otherand increments a metric. A raw storage string is never passed through. - Lamps are computed in the domain: the green, amber or red summary of a corridor or area is domain logic, tested on its own.
Use cases see only ports: interfaces declared in the domain. Each port takes a request scope (deadline, allowed source families, language) and returns domain objects plus provenance.
| Port | Operations |
|---|---|
| Gazetteer | search, get, describe a point |
| CorridorResolver | a motorway section, or a corridor from a client route |
| SituationReader | in a corridor, in an area, history |
| FuelReader, ChargingReader, SiteReader | near a point, along a corridor |
| StopReader | search, departures, disruptions |
| AccessibilityReader | facilities of a station |
| RiskReader | at a point, along a corridor |
| RuleReader | a topic |
| Provenance register | terms and freshness of each source family |
One storage adapter is the only code that knows the read contract. It translates in both directions, and the HTTP adapter translates the domain into the public shape. That gives three vocabularies and two translations:
flowchart LR
S[Storage vocabulary<br/>read contract] -- storage adapter<br/>total mapping tables --> D[Domain vocabulary<br/>aggregates, value objects]
D -- HTTP adapter<br/>DTOs --> P[Public vocabulary<br/>JSON and GeoJSON]
| Direction | Example | Guard |
|---|---|---|
| Domain → query parameters | a Corridor becomes a road, a direction and a km range, or a buffered geometry |
one function per port method; property tests over every Area variant |
| Row → domain | a storage code becomes a SituationKind; a closed-lanes count plus kind becomes a Severity; a stored price becomes a Price
|
total mapping tables: every code in the contract maps to a value or explicitly to other, tested by enumeration |
| Domain → public payload | ubiquitous-language field names in camelCase | a lint refuses public field names equal to a contract column (short allow-list such as id, name) |
A route briefing answers "what should I know along this route?" by combining five stores.
sequenceDiagram
participant H as HTTP adapter
participant U as Route briefing use case
participant P as Gazetteer
participant R as CorridorResolver
participant S as SituationReader
participant E as Fuel and charging readers
participant K as Parking reader
participant W as Weather risk reader
H->>U: query, allowed families, 2 s deadline
U->>P: resolve start and end (cached)
U->>R: corridor for road, direction, start, end
par bounded parallelism, each part with its own sub-deadline
U->>S: situations in corridor, next hours
U->>E: fuel and charging along corridor
U->>K: parking along corridor
U->>W: weather risk along corridor
end
U-->>H: briefing: lamp, situations, stops, weather, part statuses, provenance
-
Partial failure is a value: each part reports
ok,timeout,not_permittedorunavailable. The whole answer fails only if every part fails. - The licence gate applies per part: a part the key may not read is never queried.
- Database budget: each parallel query takes one admission permit. Under pressure the use case degrades to sequential reads in priority order: situations, weather, energy, parking.
-
Caching: the ETag combines the versions of all families read plus the normalised query, so a repeated poll can be answered with
304 Not Modifiedwithout touching any store.
ViaFrei API: a public, keyed, read-only REST API to live German mobility data. Design phase; nothing on these pages is a measurement of a running service. Data on viafrei.de and in every API answer is attributed to its publishers under their licences.
About
Design
- Domain Model
- API Design
- Architecture Overview
- Security and Access Keys
- Rate Limits and Priority
- Performance and Caching
- Configuration
- Observability
Data Model
Technical specification
-
Technical Specification
- Interface
- Scope, Conventions and References
- Protocol
- Common Envelope
- Resource Model
- Endpoints, Places
- Endpoints, Roads
- Endpoints, Energy and Parking
- Endpoints, Public Transport and Accessibility
- Endpoints, Weather Risk, Driving Rules and Composed Features
- Service Endpoints
- Errors
- Authentication and Authorisation
- Rate Limiting, Quotas and Priority
- Data Licensing and Attribution
- Compatibility and Versioning
- OpenAPI Skeleton
- Quality
- Delivery and operations
- Interface
Testing
- Testing Strategy
- Testing and Quality (design summary)
Engineering
Technology choice
- Technology Evaluation
- Architecture: Go
- Architecture: Rust
- Architecture: TypeScript
- Stack Comparison
- Benchmark Plan
Reference