Documentation
DocumentationArchitecture
DOCS / UWA V1 RELEASE CONTRACT SELF-HOSTED GATEWAY

Architecture

Three orthogonal dimensions: Geographic Location × Data Category × Provider Capability.

ONE GATEWAYCoordinates → eligible provider → canonical responseWhy UWA
On this page 3 sections

#Request pipeline

  1. Authenticate & validate: Verify client API key scopes (including all requested dataset scopes on /v1/datasets) and input parameters.
  2. Resolve location: Use supplied coordinates directly, or resolve unambiguous place names via internal/georesolve when APP_WEATHER_PLACE_RESOLVER=strict is enabled.
  3. Discover eligible providers per category: Filter registered adapters by dataset capability, release profile (lean_v1 vs full_experimental), geographic coverage, deployment use, credentials, health and 95% pre-flight quota gates.
  4. Rank deterministically: Order eligible candidates by explicit operator priority and measured health (requiring ≥10 observations before applying health penalties in lean_v1).
  5. Execute & handle failures: Call the selected adapter with direct-dial SSRF protection, bounded timeouts, bulkheads and circuit breakers; automatically fail over to the next eligible provider on classified upstream or validation errors.
  6. Normalize & validate integrity: Convert units to Celsius/SI, enforce 25–50 km coordinate drift ceilings and 2-hour observation age limits, validate portable IANA timezones, and return versioned canonical schemas (or a 207 Multi-Status bundle on partial multi-dataset availability).

#Package map

Trace these eleven logical modules through internal/routing (including datasets.go), internal/georesolve, internal/providerpolicy, internal/provider, internal/reliability, internal/normalization, internal/cache, internal/quota, internal/capability and providers/. Server routes are wired in internal/routing/router.go.

#Provenance and partial availability

Use meta.provider, meta.attribution, meta.cached and meta.fallback to inspect response origin. When requesting multiple categories for one location via GET /v1/datasets, UWA returns 200 OK if all categories succeed, or 207 Multi-Status with meta.partial=true containing successful data alongside structured per-category errors. Each request targets one geographic location; UWA does not expose a multi-location batch endpoint.

Canonical contracts: docs/openapi.yaml (lean_v1) and docs/openapi.experimental.yaml · Verify against your build before production use.

Search local documentation. No external requests.

↑↓ to move · Enter to openESC to close