missions/_docs/02_document/system-flows.md

# Azaion.Missions — System Flows

> **NOTE (forward-looking)**: route prefixes, identifiers, and cascade chains in this document reflect the **post-rename, post-GPS-Denied-removal** state. Today's source still uses `[Route("flights")]`, `[Route("aircrafts")]`, `Aircraft*` / `Flight*` filenames, and the cascade still touches `orthophotos` + `gps_corrections`. Renames + cascade shrink tracked under Jira AZ-EPIC children B5 / B6 / B7 / B8. Per-flow `.md` files under `diagrams/flows/` follow the same convention.

## Flow Inventory

| # | Flow Name | Trigger | Primary Components | Criticality |
|---|-----------|---------|--------------------|-------------|
| F1 | Vehicle CRUD | Operator UI HTTP | `01_vehicle_catalog` → `04_persistence` | High |
| F2 | Mission create / read / update | Operator UI HTTP | `02_mission_planning` → `04_persistence`, with `01_vehicle_catalog` existence check | High |
| F3 | Mission delete with cross-service cascade | Operator UI HTTP `DELETE /missions/{id}` | `02_mission_planning` → `04_persistence` (touches `map_objects`, `media`, `annotations`, `detection`, `waypoints`, `missions`) | **Critical** (data integrity; not transaction-wrapped today) |
| F4 | Waypoint create / read / update / delete | Operator UI HTTP | `02_mission_planning` (`WaypointService`) → `04_persistence` | High (delete is a cross-service cascade variant of F3) |
| F5 | JWT bearer validation | Every protected request | `05_identity` (pipeline middleware) | **Critical** (cross-cutting; applies to every authenticated route) |
| F6 | Service startup + schema migration | Process start | `07_host` → `04_persistence` (`DatabaseMigrator.Migrate`) | High (one-shot per restart; B9 `DROP` runs here on legacy devices) |
| F7 | Health probe | Container orchestration / reverse proxy | `07_host` (`MapGet("/health")`) | Medium |

## Flow Dependencies

| Flow | Depends on | Shares data with |
|------|------------|------------------|
| F1 | F6 (schema must exist) | F2 (mission references `vehicle_id`) |
| F2 | F1 (vehicle existence check on create / update), F5 (auth), F6 | F3 (deletion), F4 (waypoint owner) |
| F3 | F2 (a mission must exist to delete it), F5, F6 | F4 (waypoint cascade is a sub-walk), `annotations` + detection pipeline (cross-service tables) |
| F4 | F2 (mission must exist to nest waypoints under it), F5, F6 | F3 (mission delete also walks all waypoint sub-trees) |
| F5 | None | Every protected flow (F1–F4) |
| F6 | None | Every flow (no flow can run before the schema is in place) |
| F7 | None | None |

## Cross-cutting concerns (apply to all HTTP flows)

These behaviors wrap every flow at the pipeline level. They are described once here rather than repeated in each flow:

1. **JWT bearer validation (F5)**. ASP.NET Core's `JwtBearerHandler` runs on every request marked `[Authorize]`. Validation is local ECDSA-SHA256 against `admin`'s JWKS, which this service fetches once at startup (lazy, on the first protected request) and caches via `Microsoft.IdentityModel.Protocols.ConfigurationManager<JsonWebKeySet>`; subsequent request-path validation does not call `admin`. The handler enforces `iss == JWT_ISSUER`, `aud == JWT_AUDIENCE`, `exp` (with 30-second clock skew), and pins `alg` to `EcdsaSha256` (defends against HS256-confusion). Failures surface as `401 Unauthorized` (no token / signature / claims / lifetime invalid) or `403 Forbidden` (token valid but missing the `"FL"` permission claim). See `diagrams/flows/flow_jwt_validation.md` for the sequence.
2. **Permission gate**. Every controller action in `01_vehicle_catalog` and `02_mission_planning` carries `[Authorize(Policy = "FL")]`. The policy requirement is satisfied by a `permissions` claim equal to `"FL"`. The policy NAME is referenced as a raw string in feature controllers — a typo would silently turn into a permanent 403 (see `module-layout.md` § Verification Needed #4).
3. **Global exception → JSON middleware**. `ErrorHandlingMiddleware` (`06_http_conventions`) is registered FIRST in the pipeline. It maps `KeyNotFoundException → 404`, `ArgumentException → 400`, `InvalidOperationException → 409`; everything else → 500 with the stack trace logged. Wire shape: entity / DTO bodies are PascalCase (suite-spec divergence — see `architecture.md` ADR-002); the global error envelope is camelCase already (accidental match — anonymous object literal `new { statusCode, message }` uses lowercase property names) but still missing the spec's `errors` field.
4. **No correlation ID, no request-level audit trail**. Logs are timestamp-only; supporting a production incident requires grep-by-timestamp.

---

## Flow F1: Vehicle CRUD

See `diagrams/flows/flow_vehicle_crud.md`.

**Description**: Full CRUD over the vehicle catalog. Every endpoint requires the `"FL"` permission. The list endpoint is **unpaginated by spec**; create + update + setDefault contain the "exactly one default vehicle" exclusivity rule that is **stricter than spec** (see `01_vehicle_catalog` Caveats #1 and Jira AZ-551 / B12 for the resolution decision).

**Preconditions**: Service is running; schema is in place (F6); caller holds a JWT with `permissions=FL`.

**Key sequence steps** (happy path, create with `IsDefault=true`):

1. UI → `POST /vehicles { Name, VehicleType, IsDefault: true, ... }` (with `Authorization: Bearer <jwt>`).
2. Pipeline → JWT validation (F5) + policy `"FL"` check.
3. `VehiclesController.Create` → `VehicleService.CreateVehicle(req)`.
4. `VehicleService.CreateVehicle`:
   - If `req.IsDefault == true`: `UPDATE vehicles SET is_default = FALSE WHERE is_default = TRUE` *(divergence from spec — clears every other row's default flag)*.
   - `INSERT INTO vehicles VALUES (...)`.
5. `Vehicle` entity returned on the wire (PascalCase JSON).

**Error scenarios**:

| Error | Where | Detection | Recovery |
|-------|-------|-----------|----------|
| Missing or invalid JWT | Pipeline | `JwtBearerHandler` | `401 Unauthorized`; client refreshes the token at `admin` |
| JWT lacks `"FL"` permission | Pipeline | Policy evaluator | `403 Forbidden` |
| `DELETE` of a vehicle referenced by any mission | `VehicleService.DeleteVehicle` | `IsAny<Mission>(m => m.VehicleId == id)` check returns true | `InvalidOperationException` → `409 Conflict` |
| Vehicle not found by id | Get / Update / Delete / SetDefault | Entity lookup returns null | `KeyNotFoundException` → `404 Not Found` |
| Race on default-set | `VehicleService.CreateVehicle` / `UpdateVehicle` / `SetDefault` | None (no transaction) | Race window can leave 2+ `IsDefault=true` rows or zero defaults — see `01_vehicle_catalog` Caveats #1, tracked as B12 |

---

## Flow F2: Mission create / read / update

See `diagrams/flows/flow_mission_lifecycle.md`.

**Description**: Mission CRUD excluding delete (delete is F3 because of the cascade complexity). Create / update validate that the referenced `vehicle_id` exists; list is paginated (the only paginated endpoint in this service).

**Preconditions**: Service is running; schema is in place (F6); caller holds a JWT with `permissions=FL`; for create / update with `VehicleId`, the referenced vehicle must exist (F1).

**Key sequence steps** (create):

1. UI → `POST /missions { Name, VehicleId }`.
2. Pipeline → JWT + `"FL"` (F5).
3. `MissionsController.Create` → `MissionService.CreateMission(req)`.
4. `MissionService.CreateMission`:
   - `SELECT 1 FROM vehicles WHERE id = @VehicleId` (existence check, no transaction with the insert below).
   - If absent: throw `ArgumentException("VehicleId not found")` → `400` *(spec says `404`; minor divergence — see `02_mission_planning` Caveats #8)*.
   - `INSERT INTO missions (id, name, vehicle_id, created_date) VALUES (...)`.
5. `Mission` entity returned (PascalCase; LinqToDB does NOT eager-load `[Association]` navigation, so `Mission.Vehicle` and `Mission.Waypoints` serialize as `null` / `[]`).

**Error scenarios**:

| Error | Where | Detection | Recovery |
|-------|-------|-----------|----------|
| `VehicleId` does not exist on create | `MissionService.CreateMission` | Existence check returns false | `ArgumentException` → `400 Bad Request` (spec wants `404`) |
| `VehicleId` deleted between existence check and insert (TOCTOU) | `MissionService.CreateMission` | FK constraint rejects insert | Npgsql `PostgresException` → `500 Internal Server Error` (UX gap — should map to `400`) |
| Mission not found on read / update | `MissionService.GetMission` / `UpdateMission` | Entity lookup returns null | `KeyNotFoundException` → `404` |

---

## Flow F3: Mission delete with cross-service cascade *(most critical)*

See `diagrams/flows/flow_mission_cascade_delete.md`.

**Description**: `DELETE /missions/{id}` walks the full ownership graph and tears down rows in tables this service does NOT own the schema for (`media`, `annotations`, `detection`) plus its own `map_objects`, `waypoints`, and `missions`. **NOT transaction-wrapped today** (`architecture.md` ADR-006); partial failure leaves orphans. After B7, the `orthophotos` + `gps_corrections` branches are gone — they belong to the separate `gps-denied` service which manages its own cleanup.

**Preconditions**: Mission exists (`KeyNotFoundException` → `404` otherwise); schema for the borrowed tables is present in `postgres-local` (in standard edge deployment, `annotations` and detection have run their migrations on the same DB).

**Cascade order** (strictly child-before-parent, FK-driven):

```
1. DELETE FROM map_objects   WHERE mission_id = ?    (autopilot writes; this service owns schema + cleanup)
2. SELECT id FROM waypoints  WHERE mission_id = ?    → waypointIds
3. If waypointIds.Any():
     SELECT id FROM media         WHERE waypoint_id IN waypointIds → mediaIds
     SELECT id FROM annotations   WHERE media_id    IN mediaIds    → annotationIds
     DELETE FROM detection   WHERE annotation_id IN annotationIds  (cross-service: detection pipeline)
     DELETE FROM annotations WHERE id IN annotationIds              (cross-service: annotations)
     DELETE FROM media       WHERE id IN mediaIds                   (cross-service: annotations)
4. DELETE FROM waypoints WHERE mission_id = ?
5. DELETE FROM missions  WHERE id = ?
```

**Error scenarios**:

| Error | Where | Detection | Recovery |
|-------|-------|-----------|----------|
| Mission not found | Step 0 (initial existence check) | Entity lookup | `KeyNotFoundException` → `404` |
| `relation does not exist` for `media` / `annotations` / `detection` | Step 3 | Npgsql `PostgresException` (`42P01`) | `500`. **Indicates `annotations` or detection pipeline never migrated on this device** — abnormal edge deployment. See `02_mission_planning` Caveats #6 |
| Partial failure mid-cascade (network blip, lock timeout) | Any step | Npgsql exception | `500`. **Orphan rows left behind**. Re-running the same DELETE is a partial fix — already-deleted children are no-ops, remaining children proceed (see ADR-006 carry-forward) |
| `autopilot` writes a `map_object` racing this delete | Step 1 vs. concurrent insert | None | The insert may succeed AFTER step 1 reads zero rows; the orphan row stays until the next mission delete or manual cleanup. Small race window in practice (single-operator workflow) |

**Performance expectations**:

| Metric | Target | Notes |
|--------|--------|-------|
| End-to-end latency | <50ms typical | 4–7 sequential round-trips against local PostgreSQL on the same device |
| Throughput | 1 op / mission delete; not load-tested | Operator-paced; not a hot path |
| Orphan rate | 0 once transaction-wrap lands (ADR-006 carry-forward) | Today: non-zero on any failure mid-cascade |

---

## Flow F4: Waypoint create / read / update / delete

See `diagrams/flows/flow_waypoint_lifecycle.md`.

**Description**: Waypoint CRUD nested under a mission (`/missions/{id}/waypoints/*`). Delete is a scoped variant of F3's cascade — it walks `media` / `annotations` / `detection` for **one** waypoint instead of all waypoints of a mission. Same NO-transaction caveat applies (ADR-006). `UpdateWaypoint` is a **full overwrite** of every field even though the request DTO looks "partial-shaped" (see `02_mission_planning` Caveats #2). List is **unpaginated by spec**, ordered by `OrderNum`.

**Preconditions**: Parent mission exists (`KeyNotFoundException` → `404` otherwise).

**Key sequence steps** (delete one waypoint):

1. UI → `DELETE /missions/{id}/waypoints/{wpId}`.
2. Pipeline → JWT + `"FL"` (F5).
3. `MissionsController.DeleteWaypoint` → `WaypointService.DeleteWaypoint(missionId, wpId)`.
4. `WaypointService.DeleteWaypoint`:
   - Verify waypoint exists with `mission_id = @missionId AND id = @wpId` → 404 if not.
   - Resolve `mediaIds` for this one waypoint, then `annotationIds`.
   - `DELETE FROM detection WHERE annotation_id IN annotationIds`.
   - `DELETE FROM annotations WHERE id IN annotationIds`.
   - `DELETE FROM media WHERE id IN mediaIds`.
   - `DELETE FROM waypoints WHERE id = @wpId`.

**Error scenarios**: identical to F3 scoped to one waypoint.

---

## Flow F5: JWT bearer validation

See `diagrams/flows/flow_jwt_validation.md`.

**Description**: The cross-cutting auth flow that runs on every `[Authorize]` request. Signature validation is local against admin's cached JWKS public keys; the only call to `admin` is the JWKS fetch (once at startup, plus refreshes on the default schedule). Request-path validation does NOT call `admin`.

**Preconditions**: `JWT_ISSUER`, `JWT_AUDIENCE`, and `JWT_JWKS_URL` all resolved at startup via `ConfigurationResolver.ResolveRequiredOrThrow` (any missing value aborts startup); the JWT bearer middleware was registered by `AddJwtAuth(builder.Configuration)` in `07_host`.

**Key sequence steps**:

1. Request arrives at the ASP.NET Core pipeline with `Authorization: Bearer <jwt>`.
2. `JwtBearerHandler`:
   - Parse the token header.
   - Reject unless `alg ∈ ValidAlgorithms` (pinned to `EcdsaSha256` — defends against HS256-confusion).
   - Resolve signing key for the token's `kid` via the cached `ConfigurationManager<JsonWebKeySet>`. On a cold cache, this triggers a one-time HTTPS GET of `JWT_JWKS_URL` from `admin`.
   - Verify ECDSA-SHA256 signature against the matching public key.
   - Verify `iss == JWT_ISSUER`, `aud == JWT_AUDIENCE`, `exp` (with 30-second clock skew).
3. If algorithm, signature, claims, or lifetime fails: `401 Unauthorized` (without ever invoking the controller).
4. If valid: parse claims into `ClaimsPrincipal`; attach to the request.
5. Authorization policy `"FL"` evaluator checks for a `permissions` claim with value `"FL"`.
6. If absent: `403 Forbidden`.
7. If present: forward to the controller action.

**Error scenarios**:

| Error | Where | Detection | Recovery |
|-------|-------|-----------|----------|
| Missing `Authorization` header | Pipeline | `JwtBearerHandler` | `401` |
| Forged `alg: HS256` token | Pipeline | `ValidAlgorithms` pin | `401`. Pin defense — see `05_identity` Caveats #6 |
| Invalid signature | Pipeline | ECDSA verify fails | `401` |
| `iss` ≠ `JWT_ISSUER` | Pipeline | `ValidateIssuer = true` | `401` |
| `aud` ≠ `JWT_AUDIENCE` | Pipeline | `ValidateAudience = true` | `401` |
| Expired token | Pipeline | `ValidateLifetime` (with 30s skew) | `401`; client re-authenticates with `admin` |
| `kid` not in cached JWKS | `IssuerSigningKeyResolver` | No matching key | `401`. Manager refreshes on default schedule; new `kid` becomes available there |
| `admin` unreachable on first JWKS fetch | `HttpDocumentRetriever` | `HttpRequestException` | First request fails 500. Subsequent requests retry on next refresh. **Operationally**: keep `admin` reachable from edge |
| `permissions` claim missing or not `"FL"` | Policy evaluator | Claim lookup | `403` |
| JWKS rotation on `admin` | `ConfigurationManager` refresh | next scheduled refresh tick | **No coordinated redeploy needed** — new keys are picked up on refresh; old tokens with the old `kid` remain valid until expiry |

---

## Flow F6: Service startup + schema migration

See `diagrams/flows/flow_startup_migration.md`.

**Description**: One-time-per-process bootstrap. `Program.cs` builds the DI graph, runs `DatabaseMigrator.Migrate(db)` once, then starts serving HTTP. The migrator is idempotent (`CREATE ... IF NOT EXISTS`). After B9, the migrator additionally runs `DROP TABLE IF EXISTS orthophotos; DROP TABLE IF EXISTS gps_corrections;` once for fielded edge devices that previously ran the legacy schema.

**Preconditions**: `DATABASE_URL`, `JWT_ISSUER`, `JWT_AUDIENCE`, `JWT_JWKS_URL` all resolve via `ConfigurationResolver.ResolveRequiredOrThrow` (any missing value aborts startup — no hardcoded fallbacks); `postgres-local` is reachable; the `azaion` database exists. `admin` does NOT need to be reachable at this point — the JWKS fetch is lazy on the first protected request.

**Key sequence steps**:

1. Container starts → entrypoint `dotnet Azaion.Missions.dll`.
2. `Program.cs` resolves `DATABASE_URL` via `ConfigurationResolver.ResolveRequiredOrThrow` → `ConvertPostgresUrl` → Npgsql connection string.
3. Calls `AddJwtAuth(builder.Configuration)`, which resolves `JWT_ISSUER`, `JWT_AUDIENCE`, `JWT_JWKS_URL` (each via `ResolveRequiredOrThrow`), wires the `ConfigurationManager<JsonWebKeySet>`, and registers JWT bearer + `"FL"` (+ legacy `"GPS"` until B7) policies. No network call yet.
4. Reads `CorsConfig:AllowedOrigins` + `CorsConfig:AllowAnyOrigin`; runs `CorsConfigurationValidator.EnsureSafeForEnvironment` (throws in `Production` with implicit-permissive config); registers the CORS policy (permissive OR `WithOrigins`).
5. Registers controllers, middleware, scoped `AppDataConnection`, scoped service classes.
6. Builds the host. If implicit-permissive CORS applies (non-Production, empty origins, `AllowAnyOrigin=false`), logs `PermissiveDefaultWarning` at startup. Opens a single startup scope and calls `DatabaseMigrator.Migrate(db)`:
   - `CREATE TABLE IF NOT EXISTS vehicles (...)`.
   - `CREATE TABLE IF NOT EXISTS missions (...)`.
   - `CREATE TABLE IF NOT EXISTS waypoints (...)`.
   - `CREATE TABLE IF NOT EXISTS map_objects (...)`.
   - `CREATE INDEX IF NOT EXISTS ix_missions_vehicle_id ...` and similar.
   - **B9 one-shot**: `DROP TABLE IF EXISTS orthophotos; DROP TABLE IF EXISTS gps_corrections;`.
7. Registers `ErrorHandlingMiddleware` FIRST in the pipeline; mounts CORS, auth, controllers, `MapGet("/health")`, Swagger UI.
8. `app.Run()` — ready to serve HTTP on port 8080.

**Error scenarios**:

| Error | Where | Detection | Recovery |
|-------|-------|-----------|----------|
| Missing `DATABASE_URL` / `JWT_ISSUER` / `JWT_AUDIENCE` / `JWT_JWKS_URL` | Step 2 or 3 | `ResolveRequiredOrThrow` throws `InvalidOperationException` | Process exits non-zero with a message naming the env var and config key. Watchtower restarts, but the new container hits the same failure until the value is provided |
| CORS misconfigured in `Production` (empty origins + `AllowAnyOrigin != true`) | Step 4 | `EnsureSafeForEnvironment` throws | Process exits with `MissingOriginsMessage`. **Fix**: set `CorsConfig:AllowedOrigins` or explicit `AllowAnyOrigin=true` |
| `postgres-local` unreachable | Step 6 | Npgsql connection failure | Process exits non-zero. Watchtower restarts the container; `flight-gate` prevents restart mid-mission |
| `azaion` database does not exist | Step 6 | Npgsql `3D000` (`invalid_catalog_name`) | Process exits. Operator must create the database (provisioning concern, not this service) |
| `DROP TABLE IF EXISTS orthophotos` fails because the table is being read by `gps-denied` | Step 6 (B9 one-shot) | Lock timeout | Process exits. Restart loop until `gps-denied` releases the lock — should be moments. **Out-of-band ordering**: deploy `gps-denied` first so it has its own copy before `missions` drops the legacy tables |
| Migrator partial failure mid-statement | Step 6 | Npgsql exception | Process exits. Each statement is individually idempotent (`IF NOT EXISTS`) so the next startup retries safely |

---

## Flow F7: Health probe

See `diagrams/flows/flow_health_probe.md`.

**Description**: `GET /health` returns `{ "status": "healthy" }` with no auth. Used by container orchestration (Watchtower / docker compose healthcheck) and any reverse-proxy upstream check. Does NOT verify DB connectivity today — only confirms the process is up and the HTTP pipeline is serving.

**Preconditions**: HTTP pipeline is serving (i.e., `app.Run()` reached).

**Key sequence steps**:

1. Probe → `GET /health` (no `Authorization` header required).
2. `MapGet("/health")` returns `Results.Ok(new { status = "healthy" })`.

**Error scenarios**: none meaningful — if the pipeline is up the response is always 200. If the process is down, the probe fails at TCP-connect time and orchestration restarts it.

**Future improvement (carry-forward)**: gate `/health` on a DB ping so `flight-gate` and reverse-proxy checks reflect actual readiness rather than process liveness. Today the migrator runs at startup and crashes the process on DB failure, which is a coarse but workable substitute.

---

## Mermaid diagram conventions

Per the suite documentation conventions:

- **Participants** match `components/[##]_[name]` directories.
- **Node IDs** are camelCase, no spaces.
- **Decision nodes** use `{Question?}` format.
- **Start / End** stadia use `([label])`.
- **External systems** (`autopilot`, `annotations`, detection pipeline, `gps-denied`, `admin`, the React `ui`) use `[[label]]` subroutine shape and live in their own subgraphs.
- **No styling** — let the renderer theme handle it.