Repository navigation
Spec Architecture Decisions
Part of the Technical Specification. Requirement prefix: ADR. Corresponds to arc42 section 9, "Architecture decisions".
An architecture decision record (ADR) captures one significant decision: its context, the options, the choice and its consequences. ADRs are immutable once accepted; a later decision supersedes an earlier one instead of editing it.
stateDiagram-v2
[*] --> Proposed: pull request opens the ADR
Proposed --> Accepted: owner approves
Proposed --> Rejected: owner declines
Accepted --> Deprecated: no longer relevant
Accepted --> Superseded: a newer ADR replaces it
Rejected --> [*]
Deprecated --> [*]
Superseded --> [*]
| ID | Requirement | Verification |
|---|---|---|
| ADR-001 | Every decision that is costly to reverse (language, storage access, authentication model, public interface conventions, hosting shape) MUST be recorded as an ADR before the implementing change merges. | Review |
| ADR-002 | ADRs MUST live in the repository under docs/adr/NNNN-title.md, numbered sequentially, and be mirrored in the index below. |
Lint |
| ADR-003 | An accepted ADR MUST NOT be edited except to change its status and add a "superseded by" link. | Review |
| ADR-004 | Every deviation from a SHOULD of this specification MUST be recorded as an ADR naming the requirement id. | Review |
| ADR-005 | An ADR MUST cite the requirement ids and quality scenarios it affects. | Review |
# ADR-NNNN: <short decision title>
- Status: proposed | accepted | rejected | deprecated | superseded by ADR-MMMM
- Date: YYYY-MM-DD
- Deciders: <roles>
- Requirements affected: <ids, for example NFR-PERF-002, QAS-PERF-01>
## Context
The forces at play: requirements, constraints, risks. Facts, not opinions.
## Options considered
1. Option A: summary, pros, cons, evidence
2. Option B: …
## Decision
The option chosen, in one sentence, then the reasoning.
## Consequences
What becomes easier, what becomes harder, follow-up work, the risks accepted.
## Validation
How we will know the decision holds (a test, a benchmark, a metric) and when it is reviewed.| ADR | Title | Status | Date |
|---|---|---|---|
| ADR-0001 | Implementation stack for viafrei-api: Go | accepted | 2026-11-01 |
| ADR-0002 | Path-based major versioning at api.viafrei.de
|
accepted (as the recommendation on [[API Address | API-Address]]) |
| ADR-0003 | Ambiguous place answered with 422, not 409
|
proposed | 2026-11-01 |
| ADR-0004 | Instants in UTC with a Europe/Berlin local rendering field | proposed | 2026-11-01 |
| ADR-0005 | Safe query POST on long-route operations |
proposed | 2026-11-01 |
ADR-0003 to ADR-0005 record the choices this specification makes where earlier pages were silent or different.
- Status: accepted (Go)
- Date: 2026-11-01
- Deciders: the owner, on the evidence of the benchmark
- Requirements affected: NFR-PERF-001, NFR-PERF-002, NFR-PERF-003, RATE-017, NFR-PORT-001, NFR-MAINT-001
The service must enforce a hard 2 s deadline with storage-side cancellation, protect a shared store with priority admission, run in a small memory footprint at first, and be built largely with the help of AI coding agents. The candidates and their designs are on Architecture: Go, Architecture: Rust and Architecture: TypeScript.
- Go: native server-side query cancellation in the mainstream driver; small, predictable footprint; mature OpenAPI tooling.
- Rust: the smallest footprint and strongest compile-time guarantees; cancellation needs an explicit guard; slower iteration.
- TypeScript: shared language with the rest of the platform; largest footprint; cancellation needs an explicit cancel request.
Go, chosen by the owner on 2026-11-01 as the Stack Comparison recommends. The implementation follows Architecture: Go from milestone 0.2.0 on. The benchmark on Benchmark Plan remains the validation below; if Go fails it, this ADR is superseded rather than edited.
Every requirement in this specification is stack-neutral, so the choice changes no interface. It fixes the tool names in Spec: Secure SDLC and Supply Chain and Spec: Test Strategy where they are stack-specific.
Benchmark checks 1 to 4 pass for the chosen stack; the cancellation and overload acceptance tests (NFR-PERF-002, RATE-017) stay green in CI.
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