HydraIssues

Supersedes the #619 proposal to add a Market entity to hydradistrict. Markets and infrastructure are different domains, so markets get their own loosely coupled service: hydratam.

Scaffold is complete and committed at /home/claude-user/hydratam. Not yet pushed, tagged or deployed.

Why separate

hydradistrict models compute locations: id, name, provider, coordinates, service URLs. A market is a commercial object: NUTS regions, a priority tier, candidate cities, a rationale per city. Putting both in one YAML store would have coupled a sales decision to an infrastructure record and given one service two reasons to change.

The coupling between them is one optional outbound read. Without a hydradistrict URL hydratam starts normally, serves every market, and the atlas hides the district layer. Coverage endpoints return 503 with a setup_url, and health stays ok with coverage.configured=false. A missing optional integration is not a fault.

What is in the scaffold

Same conventions as hydradistrict: Go + Cobra, YAML store with no database, hydraauth bearer tokens, hydramonitor SSE, hydraserve autocert, auto-update from releases.experiencenet.com, multi-arch OCI image.

Endpoints:

• GET/POST/PUT/DELETE /api/v1/markets and /api/v1/markets/{id}
• GET /api/v1/tiers, the priority vocabulary with live counts
• GET /api/v1/regions and /api/v1/regions/{nuts}, the join surface: given a NUTS region, is it a target and at what tier
• GET /api/v1/markets/{id}/coverage and /api/v1/coverage, distance from each city to the nearest district
• GET /atlas and /atlas/geometry.json, the map interface

CLI: serve, seed (--dry-run, --replace), geometry build, version, update.

Seeded with the 15 markets from #603: 32 NUTS 2 regions, 47 cities, 3 live venues.

Verified end to end

• Full suite green, go vet clean, gofmt clean.
• Seed is idempotent: second run reports Created 0, updated 0, skipped 15.
• Store guards: one NUTS region cannot belong to two markets (409), invalid NUTS codes and out-of-range tiers rejected at 400, writes need a token (401), reads are open.
• Atlas verified in a headless browser against the running service: 276 regions drawn, 32 targets, 47 city markers, selection zooms to the market and shows per-city distances.
• Coverage verified both ways: against a district source with coordinates (Antwerp 41.3 km, Bruges 88.6 km from bxl1, matching independent calculation) and with the integration off.
• hydratam geometry build reproduces the committed boundary file byte for byte from the Eurostat source.

Design decisions worth knowing

Tier 0 is a real state. It means researched but not yet placed in the priority sequence, not lowest priority. It sorts after tier 4 and is filterable with ?tier=0, so open decisions are findable. Four markets from #603 sit there today.

Content is on disk, not go:embed. web/atlas.html, data/geo/, docs/ and seed/ are COPY'd into the image at the same paths they have in the repo. The atlas can be edited and reloaded with no rebuild.

A retired NUTS code fails loudly. TestEverySeededRegionExistsInTheGeometry asserts every market's nuts_ids exist in the shipped geometry. Verified it catches the real case: reintroducing NL33 for Zuid-Holland fails the test with a message naming the market and the code. Without it the only symptom is a region that quietly does not paint.

Open, needing a decision

1. Tier the four unranked markets (North Rhine-Westphalia, Midi-Pyrenees, Silesia, Prague) or drop them. Tracked from #603.
2. Narrow the three German Laender and Flanders from NUTS 1 to the specific NUTS 2 regions actually wanted. Baden-Wuerttemberg is tier 3 only because of ZKM in DE12 Karlsruhe, but currently claims all four DE1 regions.
3. Provision hydratam.experiencenet.com (cx23, hydraexperiencenet context) and deploy.
4. Replace the seeded venue list with the live hydravenues feed. Only the three venues named in #603 are placed; cloud-seven, nerdland, ad6 and mobile-kit have no confirmed coordinates.

Repository is not yet created under github.com/cederikdotcom.