Skip to content

Domain Model

mavrovde edited this page Nov 1, 2026 · 3 revisions

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 contexts

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

Context map

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
Loading
  • 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.

Model rules

  • Time: instants are stored and sent in UTC (2026-11-01T13:05:00Z); where people read them, a …Local companion 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: other and 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.

Read ports

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

Anti-corruption layer

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]
Loading
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 composed feature: route briefing

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
Loading
  • Partial failure is a value: each part reports ok, timeout, not_permitted or unavailable. 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 Modified without touching any store.

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally