Skip to content

Spec Architecture Decisions

mavrovde edited this page Nov 13, 2026 · 3 revisions

Spec: Architecture Decision Records

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.

1. Process

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 --> [*]
Loading
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

2. Template

# 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.

3. Index

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.

4. ADR-0001: Implementation stack for viafrei-api

  • 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

Context

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.

Options considered

  1. Go: native server-side query cancellation in the mainstream driver; small, predictable footprint; mature OpenAPI tooling.
  2. Rust: the smallest footprint and strongest compile-time guarantees; cancellation needs an explicit guard; slower iteration.
  3. TypeScript: shared language with the rest of the platform; largest footprint; cancellation needs an explicit cancel request.

Decision

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.

Consequences

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.

Validation

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.

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally