# Phase 2b — Refactoring Roadmap

**Run**: 02-coupling-refactoring
**Date**: 2026-05-10

## Solution Assessment

Acceptance criteria (`_docs/00_problem/acceptance_criteria.md`) all map to public HTTP behavior. None of the proposed changes alter that behavior — they redistribute internal ownership. The smoke + unit suite remains the gate.

## Gap Analysis

| Acceptance Criterion (paraphrased) | Current State | Post-Refactor State | Verification |
|------------------------------------|---------------|---------------------|--------------|
| AC: download single tile by lat/lon/zoom returns image metadata | Endpoint inlines logic (Program.cs:206) | Endpoint delegates to `ITileService.DownloadAndStoreSingleTileAsync` | Smoke `RunGetTileByLatLonTest` |
| AC: serve tile by z/x/y returns image bytes | Endpoint inlines logic + cache (Program.cs:141) | Endpoint delegates to `ITileService.GetOrDownloadTileAsync` | Manual smoke (no integration test exists for `/tiles/{z}/{x}/{y}` — note as a follow-up coverage gap) |
| AC: region processing pipeline | RegionService in `Services` csproj | RegionService in `Services.RegionProcessing` csproj | Smoke `RunRegionProcessingTest_200m_Zoom18` + unit RegionServiceTests |
| AC: route management pipeline | RouteService in `Services` csproj | RouteService in `Services.RouteManagement` csproj | Smoke `RunRouteWithTilesZipTest` + unit RouteServiceTests |
| AC: zoom validation rejects invalid zoom | GoogleMapsDownloaderV2 in `Services` csproj | Same class in `Services.TileDownloader` csproj | Unit GoogleMapsDownloaderZoomValidationTests |

**Coverage gap noted but out of scope**: there is no integration test exercising the `/tiles/{z}/{x}/{y}` endpoint specifically. The unit-level cache logic in C01 will be tested via new TileService unit tests; integration coverage can be added in a future cycle.

## Phased Roadmap

### Phase A — Endpoint routing (low risk, sequential)

1. **AZ-NEW-1 (refactor C01)** — `ITileService.GetOrDownloadTileAsync(z,x,y)` + ServeTile handler thinning.
2. **AZ-NEW-2 (refactor C02)** — `ITileService.DownloadAndStoreSingleTileAsync(lat,lon,zoom)` + GetTileByLatLon handler thinning.

After Phase A, F3 from the architecture baseline is resolved. Smoke + unit suite stays green.

### Phase B — Project split (medium risk, sequential due to compiler dependency chain)

3. **AZ-NEW-3 (refactor C03)** — Create `Services.TileDownloader`, `Services.RegionProcessing`, `Services.RouteManagement` csprojs and move the seven files.
4. **AZ-NEW-4 (refactor C04)** — Update `SatelliteProvider.Tests` and `SatelliteProvider.IntegrationTests` to reference the new csprojs.
5. **AZ-NEW-5 (refactor C05)** — Update `SatelliteProvider.Api` csproj, `Program.cs` namespaces, and `Dockerfile` COPY paths.

After Phase B, F4 from the architecture baseline is resolved. The solution builds, smoke + unit suite stays green, the API container still runs.

### Phase C — Documentation (low risk, last)

6. **AZ-NEW-6 (refactor C06)** — Update `module-layout.md`, `architecture.md`, refresh `architecture_compliance_baseline.md` (mark F3, F4 Resolved; correct F5).

After Phase C, doc-code parity is restored.

## Hardening Tracks

User Phase 0 + Phase 1 approvals already excluded hardening. The only optional track that would fit is:

- **Track A — Tech Debt**: pre-existing FluentAssertions community-license warning would belong here, but it's a licensing decision (legal cost vs. switching to `Shouldly` or `xunit.assert`), not a code-structure decision. Surfacing as a follow-up backlog item rather than including in this run.

No hardening tracks added to this run. Pure structural refactor.

## Applicability Gate

Every roadmap item carries `Selected` status from `research_findings.md`. No `Rejected`, `Experimental only`, or `Needs user decision` entries remain. Gate: **passed**.

## Self-Verification

- [x] All ACs mapped to current vs post-refactor state.
- [x] Phased order respects compiler dependencies (endpoint refactor before split).
- [x] Each item has a verification path (smoke or unit suite).
- [x] No item violates the Project Constraint Matrix.
- [x] Hardening track decision recorded.
