Skip to content

Spec Risks Assumptions Constraints

mavrovde edited this page Nov 13, 2026 · 2 revisions

Spec: Risks, Assumptions and Constraints

Part of the Technical Specification. Prefixes: CON (constraints), ASM (assumptions), RISK (risks). Corresponds to arc42 sections 2 ("Constraints") and 11 ("Risks and technical debt").

1. Constraints

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

2. Assumptions

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

3. Risk register

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

Requirements

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

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally