# Phase 0 — Baseline Metrics (03-code-quality-refactoring)

**Date**: 2026-05-10
**Mode**: Automatic (user-discovered scope)
**Goal (user request)**: Assess current code, identify bad practices, produce steps to eliminate them.

## Scope

- Full codebase, all 8 production/test projects.
- No specific feature change: this is a quality-focused refactor cycle, after the recent coupling refactor (`02-coupling-refactoring`) closed all five Architecture-compliance findings.
- Behavior preservation required: smoke + unit suite must remain green.

## Refactoring Goals (Phase 0a)

These are the exit criteria that Phase 6 (Verification) will check against. They are deliberately framed in terms of *categories of bad practice* rather than fixed file-level changes — the precise list is produced by Phase 1.

1. **Code-smell inventory**: every C# source file in the production projects (`Api`, `Common`, `DataAccess`, `Services.*`) is reviewed for: error handling gaps, scope discipline (long methods / SRP violations), magic numbers, hidden side effects, async-correctness (`async void`, missing `ConfigureAwait` / `CancellationToken`), thread-safety in hosted services, and duplication across the three `Services.*` siblings.
2. **Inventory delivered as `list-of-changes.md`** with severity (Low / Medium / High), risk, and dependencies — same template used for `01-testability-refactoring` and `02-coupling-refactoring`, so the change list is directly consumable by the implement skill.
3. **Roadmap (Phase 2)** ranks the entries by ROI (impact ÷ risk×effort) and groups them into batches that fit the 2–5-point complexity policy from the user's tracker rules.
4. **No regression** in unit (37) or integration smoke (5 scenarios) suites at Phase 6 verification.
5. Open question for Phase 0 BLOCKING gate: does the user want the run to **execute** (Phases 3–7) or **stop after roadmap** (Quick Assessment, Phases 0–2 only)?

## Constraints

- **No public HTTP route changes.** `/api/satellite/tiles/latlon`, `/api/satellite/tiles/{z}/{x}/{y}`, `/api/satellite/request`, `/api/satellite/route` shapes are stable.
- **No database schema changes** (would require migration sequencing and is out of scope).
- **No DI-graph re-ordering** that would change observable startup behavior of the hosted services (`RegionProcessingService`, `RouteProcessingService`).
- **Architecture Vision** (`_docs/02_document/architecture.md` H2) is authoritative. Any proposed change that conflicts with it must be flagged, not silently accepted.

## Current Code Topology

| Project | LOC (.cs, excl. bin/obj) | Files | Notes |
|---------|--------------------------|-------|-------|
| SatelliteProvider.Api | 380 | 1 (`Program.cs`) | Minimal-API endpoints + DI wiring |
| SatelliteProvider.Common | 474 | 25 | DTOs, interfaces, configs, GeoUtils |
| SatelliteProvider.DataAccess | 614 | 11 | Repositories, Entities, Migrations |
| SatelliteProvider.Services.TileDownloader | 620 | 3 | `TileService`, `GoogleMapsDownloaderV2`, DI ext. |
| SatelliteProvider.Services.RegionProcessing | 564 | 4 | `RegionService`, hosted service, queue, DI ext. |
| SatelliteProvider.Services.RouteManagement | 1055 | 3 | `RouteService`, `RouteProcessingService`, DI ext. ← largest unit |
| SatelliteProvider.Tests | 1221 | 6 | xUnit unit tests |
| SatelliteProvider.IntegrationTests | 1434 | 10 | Console runner, integration scenarios |

Total production C# LOC: **3 707** across 47 files (Api + Common + DataAccess + 3 × Services).
Total test C# LOC: **2 655** across 16 files.

## Test Coverage Baseline (carried forward + verified)

- **Unit suite** (`SatelliteProvider.Tests`): 37 `[Fact]`/`[Theory]` annotations (FINAL_report of 02-coupling claimed 40 — small discrepancy; will reconcile in Phase 6 against `dotnet test --list-tests`).
- **Integration smoke** (`scripts/run-tests.sh --smoke`): 5 scenarios, last green run **2026-05-10**, wall-clock **111.86 s** (`_docs/03_implementation/test_run_step7.md`).
- Coverage % not measured (no Coverlet wired up; would add as a Phase 0 sub-task only if the user wants it gating verification).

## Architecture Compliance Baseline (carried forward)

`_docs/02_document/architecture_compliance_baseline.md` — **all 5 findings Resolved** by epic AZ-309. F1, F2 (High) and F3, F4 (Medium) and F5 (Low). No new architecture findings have been opened since.

## Complexity / Static-Analysis Tools

Not present in this repository:

- No Coverlet / dotCover / fine-grained coverage runner.
- No `dotnet format --verify-no-changes` gate.
- No SonarLint / Roslyn-analyzer ruleset beyond defaults.
- No cyclomatic-complexity tool wired up.

These gaps are *themselves* candidate findings for Phase 1 (tooling category).

## Functionality Inventory

| Endpoint / Hosted Service | Owner Project | Status | Smoke Coverage |
|---------------------------|---------------|--------|----------------|
| `GET /api/satellite/tiles/{z}/{x}/{y}` | Api → Services.TileDownloader | live | ✓ (TileTests.RunGetTileByLatLonTest) |
| `GET /api/satellite/tiles/latlon` | Api → Services.TileDownloader | live | ✓ |
| `GET /api/satellite/tiles/mgrs` | Api | stub (returns 501) | not exercised |
| `POST /api/satellite/request` | Api → Services.RegionProcessing | live | ✓ (RegionTests.RunRegionProcessingTest_200m_Zoom18) |
| `GET /api/satellite/region/{id}` | Api → Services.RegionProcessing | live | ✓ |
| `POST /api/satellite/route` | Api → Services.RouteManagement | live | ✓ (BasicRouteTests.RunSimpleRouteTest, ExtendedRouteTests.RunRouteWithTilesZipTest) |
| `GET /api/satellite/route/{id}` | Api → Services.RouteManagement | live | ✓ |
| `POST /api/satellite/upload` | Api | stub (returns 501) | not exercised |
| `RegionProcessingService` (BackgroundService) | Services.RegionProcessing | live | exercised via region scenarios |
| `RouteProcessingService` (BackgroundService) | Services.RouteManagement | live | exercised via route scenarios |

## Self-Verification (Phase 0)

- [x] RUN_DIR created with auto-incremented prefix `03-`.
- [x] Goals captured (5 numbered goals above).
- [x] Constraints captured (no HTTP-shape change, no schema change, no DI reorder, Architecture Vision honored).
- [x] Current topology measured by LOC and file count.
- [x] Test coverage baseline noted; coverage % flagged as not measured.
- [x] Architecture compliance baseline noted (carried from 02-coupling FINAL_report).
- [x] Functionality inventory complete (10 endpoints + 2 hosted services).
- [x] Tool gaps explicitly listed so Phase 1 can decide whether to fold them in.

## Open Question for User (BLOCKING gate)

See the Phase 0 summary presented in chat — two decisions:
1. Confirm goals and constraints above.
2. Choose: full refactor run (Phases 0–7) vs. Quick Assessment (Phases 0–2 only — produces `list-of-changes.md` + `refactoring_roadmap.md` and stops).