missions/_docs/02_document/00_discovery.md

Codebase Discovery — Azaion.Missions

NOTE (forward-looking): this discovery doc reflects the post-rename, post-GPS-Denied-removal target for this repo. Today the source still uses Azaion.Flights namespace, Aircraft*/Flight*/Orthophoto*/GpsCorrection* filenames, [Route("aircrafts"|"flights")], and migrates 6 tables. The renames + drops are tracked under Jira AZ-EPIC + child tickets B5–B12 (see plan and _autodev_state.md). The doc IS the spec for that work.

Suite Context (read first)

This workspace is one submodule of the azaion-suite meta-repo (an aggregate of 11 component submodules orchestrated by the parent at ../../). The canonical, human-confirmed documentation for what this service is supposed to do lives at:

Suite doc	Relevance to missions
../../suite/_docs/02_missions.md	Primary spec — Missions / Waypoints / Vehicles CRUD, all 15 endpoints (post-rename)
../../suite/_docs/00_top_level_architecture.md	Service topology, deployment tiers, error/pagination wire conventions
../../suite/_docs/00_database_schema.md	Authoritative ER diagram for the shared edge PostgreSQL
../../suite/_docs/00_roles_permissions.md	FL permission code consumed by this service
../../suite/_docs/04_system_design_clarifications.md	SSE conventions (relevant for downstream consumers)
../../suite/_docs/glossary.md	Suite-wide terminology
../../suite/_docs/11_gps_denied.md	NOT this service — GPS-Denied is a separate (out-of-this-repo) service
../../suite/_docs/05_security/cmmc_l2_scorecard.md	CMMC L2 row 3 finding on JWT iss/aud validation, tracked at suite level (AZ-487/AZ-494)

../../suite/_docs/_repo-config.yaml post-rename: name: missions, stack: .NET, deployment_tier: edge, primary_doc: _docs/02_missions.md.

What missions IS, in suite terms

missions is the edge-tier .NET service that owns the "mission" domain of an Azaion deployment. It runs on each Jetson / OrangePI / operator-PC alongside annotations, detections, autopilot, gps-denied, and the React ui. All edge services share one local PostgreSQL on the device; each migrates only its own tables. JWTs are minted by the remote admin service and validated locally with the shared HMAC secret. Per the spec, this service has TWO feature slots, both gated by ONE permission:

Spec feature slot	Permission	Status in code today
Vehicle Catalog (Plane / Copter / UGV / GuidedMissile inventory + default selection)	FL	Implemented (today as "aircraft catalog" with Plane/Copter only; VehicleType expansion is B6)
Mission Planning (Missions + Waypoints CRUD + cross-service cascade-delete)	FL	Implemented (today as "flight planning"; rename + cascade shrink is B6 + B7)

GPS-Denied is not a feature of this service. The orthophoto / live-GPS / GPS-correction endpoints listed in ../../suite/_docs/11_gps_denied.md live in the new (separate) gps-denied service.

Why "missions" not "flights"

The previous service name flights was too narrow. The fleet covered by VehicleType includes:

• Plane = 0 — fixed-wing UAV
• Copter = 1 — multirotor UAV
• UGV = 2 — Unmanned Ground Vehicle (per ../../hardware/_standalone/target_acquisition/target_acquisition.md)
• GuidedMissile = 3 — single-use loitering munition

A "flight" only describes air vehicles. A "mission" is the right abstraction for any of the above.

Cross-service contracts owned here

1. JWT validation — trusts admin-issued tokens via shared HMAC secret (JWT_SECRET). This service never talks to admin; it only validates.
2. Mission cascade-delete — when a mission or waypoint is deleted, this service tears down rows in media, annotations, detection (owned schema-wise by annotations + the detection pipeline) AND map_objects (written by autopilot from H3-indexed detections per ../../suite/_docs/06_autopilot_design.md). It is the only place in the system that knows the full mission ownership graph.
3. Suite-standard wire shapes — error envelope and PaginatedResponse<T> are shared with annotations, admin, satellite-provider (defined in ../../suite/_docs/00_top_level_architecture.md).

---

Repository Layout

flights/   ← post-rename: missions/
├── Auth/                          (1 file)   — JWT bearer auth setup + permission policy
├── Controllers/                   (2 files)  — REST API surface
├── DTOs/                          (15 files) — Request/response/query/shared payloads
├── Database/
│   ├── AppDataConnection.cs                  — LinqToDB DataConnection with ITable<T> properties
│   ├── DatabaseMigrator.cs                   — Bootstraps the 4 tables this service OWNS the schema for (post-B7+B9)
│   └── Entities/                  (7 files)  — LinqToDB-mapped row types (4 owned + 3 borrowed read-only stubs) (post-B7)
├── Enums/                         (5 files)  — Domain enumerations stored as INTEGER columns
├── Middleware/                    (1 file)   — Global exception → JSON error mapper
├── Entities/                      (empty dir) — likely scaffolding leftover; delete in B5
├── Infrastructure/                (empty dir) — likely scaffolding leftover; delete in B5
├── Program.cs                                — Web host composition root + URL→connection-string adapter
├── GlobalUsings.cs                           — `global using LinqToDB[.Async|.Data]`
├── Azaion.Missions.csproj                    — `Microsoft.NET.Sdk.Web`, TargetFramework `net10.0` (post-B5)
├── Dockerfile                                — Multi-arch SDK build → `dotnet/aspnet:10.0` runtime, EXPOSE 8080 (entrypoint Azaion.Missions.dll post-B10)
├── README.md                                 — One-liner; today says ".NET 8" — STALE (csproj targets net10.0)
├── .woodpecker/build-arm.yml                 — Single CI job: docker build + push on `[dev, stage, main]`
└── .gitignore

Total source files post-B7: ~33 .cs files across 7 logical directories (down from 37 today; loses Aircraft.cs renamed → Vehicle.cs, Flight.cs renamed → Mission.cs, Orthophoto.cs deleted, GpsCorrection.cs deleted, OrthophotoRequest.cs does not exist anyway).

Tech Stack

Concern	Technology	Source of evidence
Language / runtime	C# on .NET 10 (net10.0)	csproj
Web framework	ASP.NET Core (Microsoft.NET.Sdk.Web)	csproj, Program.cs
Data access	linq2db 6.2.0	csproj, AppDataConnection.cs
Database driver	Npgsql 10.0.2 (PostgreSQL — shared with all other edge services)	csproj, Program.cs (UsePostgreSQL)
Migrations	None (raw CREATE TABLE IF NOT EXISTS for the 4 owned tables, plus a one-shot DROP TABLE IF EXISTS block in B9 for legacy GPS-Denied tables)	Database/DatabaseMigrator.cs
Auth	JWT bearer, HS256 shared-secret with admin; single claim-based permission FL (post-B7)	Auth/JwtExtensions.cs
API docs	Swashbuckle 10.1.5 (Swagger UI mounted unconditionally)	csproj, Program.cs
CORS	Open default policy (AllowAnyOrigin/Method/Header)	Program.cs
Error handling	Custom middleware mapping KeyNotFoundException/ArgumentException/InvalidOperationException → 404/400/409, fallthrough → 500	Middleware/ErrorHandlingMiddleware.cs
Health endpoint	GET /health returns { status: "healthy" }	Program.cs
Container build	Dockerfile multi-arch (--platform=$BUILDPLATFORM, dotnet publish --os linux --arch $arch)	Dockerfile
CI	Woodpecker single ARM-tagged build-and-push job; tag pattern ${REGISTRY_HOST}/azaion/missions:${BRANCH}-arm (post-B10)	.woodpecker/build-arm.yml
Tests	None present — tracked in ../../suite/_docs/_process_leftovers/2026-04-22_ci-unit-test-lane-missing-projects.md	full file scan

Entry Points

• Program.cs — Web host (top-level statements). Builds DI graph, runs DatabaseMigrator.Migrate once at startup, then app.Run().
• HTTP routes (registered via MapControllers + one minimal MapGet) (post-B6 + B8):
  • [Authorize FL] vehicles/* → VehiclesController (matches spec items 10–15 in ../../suite/_docs/02_missions.md)
  • [Authorize FL] missions/* → MissionsController (matches spec items 1–9, includes nested missions/{id}/waypoints/*)
  • Anonymous GET /health
  • No GPS-Denied endpoints — those live in the separate gps-denied service.

Configuration / Secrets

Resolved at startup in Program.cs:

Key	Source order	Default (development fallback)
DATABASE_URL	IConfiguration → Environment.GetEnvironmentVariable → fallback	Host=localhost;Database=azaion;Username=postgres;Password=changeme
JWT_SECRET	IConfiguration → Environment.GetEnvironmentVariable → fallback	development-secret-key-min-32-chars!!

DATABASE_URL accepts either a postgresql://user:pass@host:port/db URL (converted via local helper ConvertPostgresUrl) or a raw Npgsql connection string. Edge compose passes DATABASE_URL: postgresql://postgres:${PG_LOCAL_PASSWORD}@postgres-local/azaion per ../../suite/_docs/00_top_level_architecture.md.

Test Layout

No tests detected. Tracked in ../../suite/_docs/_process_leftovers/2026-04-22_ci-unit-test-lane-missing-projects.md. The autodev BUILD pipeline will fill this gap (Steps 3 → 6 of existing-code flow). Sibling project would be Azaion.Missions.Tests (post-B5).

Existing Documentation

• README.md — one line, says ".NET 8" but csproj targets net10.0. STALE — fixed by Phase A1 of the rename plan.
• No inline XML doc comments on any public type observed.
• No docs/ directory in this submodule. The canonical docs live at ../../suite/_docs/ (suite level).
• This _docs/02_document/ tree is the local autodev artifact set.

Dependency Graph (file-level, internal-only) — post-rename

Modules grouped by topological layer (each module imports only from layers above it). Internal-only edges shown; external NuGet edges (LinqToDB, ASP.NET Core, Npgsql) omitted.

Layer 0 — Leaves (no internal deps)
  Enums.VehicleType, Enums.FuelType, Enums.WaypointSource,
  Enums.WaypointObjective, Enums.ObjectStatus
  DTOs.GeoPoint, DTOs.SetDefaultRequest, DTOs.UpdateMissionRequest,
  DTOs.CreateMissionRequest, DTOs.GetMissionsQuery, DTOs.PaginatedResponse,
  DTOs.ErrorResponse, DTOs.GetVehiclesQuery
  Database.Entities.Media, Database.Entities.Annotation,
  Database.Entities.Detection
  Middleware.ErrorHandlingMiddleware
  Auth.JwtExtensions
  GlobalUsings

Layer 1 — Depend on Enums (or GeoPoint)
  DTOs.CreateVehicleRequest         → Enums
  DTOs.UpdateVehicleRequest         → Enums
  DTOs.CreateWaypointRequest        → Enums, DTOs.GeoPoint
  DTOs.UpdateWaypointRequest        → Enums, DTOs.GeoPoint
  Database.Entities.Vehicle         → Enums
  Database.Entities.MapObject       → Enums
  Database.Entities.Waypoint        → Enums  (Association → Mission)
  Database.Entities.Mission         → Enums  (Associations → Vehicle, Waypoint)

Layer 2 — Database wiring
  Database.AppDataConnection        → all Database.Entities (7)
  Database.DatabaseMigrator         → Database.AppDataConnection

Layer 3 — Services
  Services.VehicleService           → AppDataConnection, Entities, DTOs
  Services.WaypointService          → AppDataConnection, Entities, DTOs, Enums
  Services.MissionService           → AppDataConnection, Entities, DTOs
                                      (cascade also touches MapObjects,
                                       Media, Annotations, Detections)

Layer 4 — HTTP surface
  Controllers.VehiclesController    → Services.VehicleService, DTOs
  Controllers.MissionsController    → Services.MissionService,
                                      Services.WaypointService, DTOs

Layer 5 — Composition root
  Program.cs                        → Auth.JwtExtensions, Database (AppDataConnection,
                                      DatabaseMigrator), Middleware.ErrorHandlingMiddleware,
                                      Services.{Vehicle,Waypoint,Mission}Service

Topological Processing Order (used for module-level documentation)

1. Enums (5)
2. Simple DTOs (8)
3. Simple Entities (3 cross-service stubs)
4. Cross-cutting leaves (3): JwtExtensions, ErrorHandlingMiddleware, GlobalUsings
5. DTOs depending on Enums (4)
6. Entities depending on Enums (4)
7. DB wiring (2)
8. Services (3)
9. Controllers (2)
10. Composition root (1)

No import cycles detected.

---

Cross-Repo Schema Ownership (the key insight)

The shared edge PostgreSQL hosts tables owned by multiple services. This service's AppDataConnection exposes ALL of them, but only migrates the 4 it owns:

Table	Schema owner	Written by	Read by missions	missions writes?
vehicles	missions	missions (VehicleService)	yes	yes (full CRUD)
missions	missions	missions (MissionService)	yes	yes (full CRUD)
waypoints	missions	missions (WaypointService)	yes	yes (full CRUD)
map_objects	missions	autopilot (per ../../suite/_docs/06_autopilot_design.md)	no	cascade-delete only
media	annotations (per ../../suite/_docs/01_annotations.md)	annotations	yes (id + waypoint_id resolution)	cascade-delete only
annotations	annotations	annotations	yes (id + media_id resolution)	cascade-delete only
detection	detection pipeline	detections / ai-training	yes (id resolution)	cascade-delete only
orthophotos	gps-denied (separate service, post-B7)	gps-denied	no	no (was: cascade-delete only)
gps_corrections	gps-denied (separate service, post-B7)	gps-denied	no	no (was: cascade-delete only)

This pattern explains the shape of AppDataConnection and DatabaseMigrator — what looks like "incompleteness" in the migrator is the deliberate per-service ownership pattern.

---

Cycles / Anomalies (post-rename)

• Entity ↔ Entity navigation (Mission.Waypoints ↔ Waypoint.Mission, Mission.Vehicle) — LinqToDB [Association] pair, not an import cycle.
• Empty directories: Entities/ and Infrastructure/ at the root are empty. Delete in B5 as part of the rename pass.
• detection table singularity: Detection.cs maps to [Table("detection")] (singular) while every other table is plural. Owned by another service — naming is THEIR call to make consistent.
• README ".NET 8" claim: contradicts net10.0 in csproj. Fix in Phase A1.

Spec ↔ Code Divergences (carried into the verification log)

#	Concern	Spec source	Code reality	Resolution
1	Service / domain naming	../../suite/_docs/02_missions.md (post-rename)	Azaion.Flights.*, [Route("flights")], [Route("aircrafts")] today	B5 + B6 + B8
2	GPS-Denied feature slot	../../suite/_docs/11_gps_denied.md (separate service)	Schema (Orthophoto, GpsCorrection) + cascade branches still in this repo	B7 + B9 (drop entirely)
3	VehicleType membership	../../suite/_docs/02_missions.md (Plane / Copter / UGV / GuidedMissile)	AircraftType { Plane, Copter } only	B6
4	Geopoint representation	../../suite/_docs/02_missions.md § "GPS (Geopoint)" + ../../suite/_docs/00_database_schema.md (Waypoints.GPS: string)	3 separate columns (lat NUMERIC, lon NUMERIC, mgrs TEXT); no auto-conversion	Out of this Epic — carry forward
5	Error wire shape	../../suite/_docs/00_top_level_architecture.md § Error Response Format (camelCase, errors: object? keyed by field)	PascalCase { "StatusCode", "Message" }; no errors; ErrorResponse DTO has List<string>? (wrong shape) and is unused	Out of this Epic — carry forward
6	Pagination wire shape	../../suite/_docs/00_top_level_architecture.md § Pagination (camelCase)	PascalCase via System.Text.Json defaults	Out of this Epic — carry forward
7	Vehicle IsDefault exclusivity	../../suite/_docs/02_missions.md § 11 + 15 (just toggles)	Code clears the flag on every other row (stricter than spec) + race-prone	B12 (decision-only ticket)
8	Vehicle listing pagination	Spec endpoint 13 says "unpaginated"	Matches spec ✓	—
9	Waypoint listing pagination	Spec endpoint 6 says "unpaginated"	Matches spec ✓	—
10	Cascade-delete chain	Spec § 9 covers mission delete cascade; § 5 covers waypoint delete	Code matches the spec's cascade order; missing transaction wrapping	B7 shrinks the chain; transaction wrap is opportunistic improvement carried forward
11	Swagger gating	Not specified	Unconditional, no IsDevelopment guard	Out of this Epic
12	CORS policy	Not specified	Open in all environments	Out of this Epic
13	JWT issuer/audience validation	CMMC L2 finding (suite-tracked, AZ-487/AZ-494)	Disabled, consistent with shared-secret model; suite-level remediation pending	Suite-level (not this Epic)
14	FL permission code name	../../suite/_docs/00_roles_permissions.md	Code carries "FL" (legacy "Flight" name) even after rename to missions	TODO in 00_roles_permissions.md; not this Epic (fleet-wide auth change)
15	FuelType for GuidedMissile	Not specified	Existing { Electric, Gasoline, Diesel } may not fit single-use missiles	Phase C decision — may spawn follow-up ticket

Cross-cutting Observations

1. No automated tests in the repository.
2. CORS allows any origin/method/header in all environments — production exposure if not overridden upstream.
3. JWT secret default (development-secret-key-min-32-chars!!) is hardcoded; production deploys MUST set JWT_SECRET.
4. Swagger UI is enabled unconditionally (no IsDevelopment guard).
5. Database password default (changeme) is hardcoded.
6. CI pipeline (.woodpecker/build-arm.yml) has only a build/push step — no test, no security scan, no migration check.
7. Schema bootstrap runs every startup (DatabaseMigrator.Migrate); idempotent (IF NOT EXISTS) but no schema versioning. The B9 DROP TABLE IF EXISTS is the one explicit destructive step in the migrator's history.