Repository navigation
Spec Risks Assumptions Constraints
mavrovde edited this page Nov 13, 2026
·
2 revisions
Part of the Technical Specification. Prefixes: CON (constraints), ASM (assumptions), RISK (risks). Corresponds to arc42 sections 2 ("Constraints") and 11 ("Risks and technical debt").
| ID | Constraint | Source |
|---|---|---|
| CON-001 | The API MUST be read-only. | [[Vision and Goals |
| CON-002 | The API MUST read only the published read contract, through a read-only role; it MUST NOT see or depend on storage internals. | [[Architecture Overview |
| CON-003 | No request MAY run longer than 2 s. | [[Principles |
| CON-004 | The API MUST NOT describe or expose how data is collected. | [[Vision and Goals |
| CON-005 | Every answer MUST carry attribution; licence terms override product wishes. | [[Principles |
| CON-006 | Hosting MUST be in Germany or the EU; at first with a tight memory and connection budget. | [[Principles |
| CON-007 | The API MUST answer the same facts as the MCP server for the same input. | [[Vision and Goals |
| CON-008 | The process MUST be public: repository, CI, releases and this wiki. | [[Development Process |
| CON-009 | Tests MUST NOT call live data providers or production. | [[Testing and Quality |
| CON-010 | The implementation stack is one of Go, Rust or TypeScript (ADR-0001). | [[Stack Comparison |
| ID | Assumption | If wrong |
|---|---|---|
| ASM-001 | (A-CAP-1) Early load is within 50 requests per second sustained and 200 per second in bursts per instance. | Scale-out stage earlier; shared limiter state |
| ASM-002 | The read contract can serve every v1 operation with indexed, bounded queries. | Operations deferred or reshaped; contract additions on the platform side |
| ASM-003 | The platform maintains a cheap freshness version per source family. |
304 rate falls; more storage load |
| ASM-004 | The licence review permits API redistribution for enough families to make each domain useful. | Domains launch later or for fewer use classes |
| ASM-005 | Key holders are organisations or developers who accept API terms; no consumer self-service in v1. | DPIA and a sign-up design needed (GOV-004) |
| ASM-006 | A single instance is enough for the first stage, so in-process limits are exact. | NFR-SCALE-003 applies |
| ASM-007 | The rate-limit header draft remains stable enough to implement; the pinned revision is documented. | Header syntax change in a minor release with notice |
| ASM-008 | Clients can supply a route for "along" questions; the API does not route. | Demand for routing is redirected to routing services |
Likelihood and impact on a 1 (low) to 3 (high) scale; score = likelihood × impact.
| ID | Risk | L | I | Score | Mitigation | Owner |
|---|---|---|---|---|---|---|
| RISK-001 | Licence violation: data served to a use class its terms forbid | 1 | 3 | 3 | Default-deny gate in the query plus post-check, signed-off matrix, alert at one violation (SEC-030 to SEC-032, LIC-009) | owner |
| RISK-002 | The shared store is starved by API load | 2 | 3 | 6 | Role connection limit and timeout, permits = pool, priority admission (NFR-CAP-002) | operator |
| RISK-003 | Storage-side cancellation fails in the chosen stack | 1 | 3 | 3 | Benchmark check 1 eliminates such a candidate; cancellation test in CI (NFR-PERF-002) | maintainers |
| RISK-004 | A leaked key is abused | 2 | 2 | 4 | Secret scanning patterns, usage anomaly alert, fast revocation (SSC-013, OPS-012, SEC-042) | operator |
| RISK-005 | Volumetric denial of service beyond the edge's capacity | 2 | 2 | 4 | Early refusal, per-IP limits; a scrubbing service is a later option | operator |
| RISK-006 | Supply-chain compromise of a dependency | 1 | 3 | 3 | Dependency policy, pinning, SBOM, provenance, scanning (SSC) | maintainers |
| RISK-007 | Read-contract change breaks the API | 2 | 2 | 4 | Contract file, contract tests on both sides, readiness refusal on incompatible major (VER-009) | maintainers |
| RISK-008 | Parity drift between API and MCP server | 2 | 2 | 4 | Shared fixtures, parity suite (FR-GEN-002) | maintainers |
| RISK-009 | Small team, single operator: on-call fatigue, bus factor | 3 | 2 | 6 | Automation, runbooks, conservative SLOs, second maintainer, tier hours (OPS) | owner |
| RISK-010 | The specification grows faster than the implementation | 2 | 1 | 2 | Phased roadmap; every requirement traced to its page and method in the traceability matrix | owner |
| RISK-011 | Stale data presented as current | 2 | 2 | 4 | Per-family freshness, data_stale warning, lamp unknown (NFR-FRESH, FR-BRIEF-006) |
maintainers |
| RISK-012 | Keys used in browsers are exposed | 3 | 1 | 3 | Documentation warning, CORS allow-list, quotas (PROT-050, PROT-053) | owner |
| ID | Requirement | Verification |
|---|---|---|
| RISK-100 | The risk register MUST be reviewed at each minor release and after every SEV1 or SEV2 incident; risks with score ≥ 6 MUST have an issue with an owner. | Review |
| RISK-101 | An assumption that is invalidated MUST be recorded here with the date and the resulting ADR or issue. | Review |
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