missions/_docs/02_document/diagrams/flows/flow_startup_migration.md

Flow F6 — Service startup + schema migration

One-shot per process start. Idempotent migrator (CREATE ... IF NOT EXISTS). Post-B9 the migrator additionally DROP TABLE IF EXISTS orthophotos / gps_corrections for fielded edge devices that previously ran the legacy schema.

Description

Program.cs builds the DI graph from environment, runs DatabaseMigrator.Migrate(db) once inside a startup scope, then starts serving HTTP. The migrator only owns the 4 tables this service is responsible for (vehicles, missions, waypoints, map_objects); the borrowed tables (media, annotations, detection) are migrated by their owner services in their own startups.

Preconditions

• DATABASE_URL, JWT_ISSUER, JWT_AUDIENCE, JWT_JWKS_URL all resolve via ConfigurationResolver.ResolveRequiredOrThrow. Any missing value aborts startup before the host is built — there are no hardcoded fallbacks.
• postgres-local is reachable.
• The azaion database itself exists in PostgreSQL (created at provisioning time, NOT by this migrator).
• admin does NOT need to be reachable at process start. The JWKS fetch is lazy — it happens on the first protected request, not during the startup sequence diagrammed below.

Sequence Diagram

sequenceDiagram
    autonumber
    participant Docker as Docker / Watchtower
    participant Host as 07_host (Program.cs)
    participant Cfg as IConfiguration
    participant Identity as 05_identity
    participant DI as DI container
    participant Migrator as DatabaseMigrator
    participant DB as postgres-local

    Docker->>Host: ENTRYPOINT dotnet Azaion.Missions.dll
    Host->>Cfg: ResolveRequiredOrThrow DATABASE_URL → ConvertPostgresUrl → Npgsql connection string
    Host->>Cfg: ResolveRequiredOrThrow JWT_ISSUER, JWT_AUDIENCE, JWT_JWKS_URL — throw on any miss
    Host->>Identity: AddJwtAuth(builder.Configuration) — DI registration + ConfigurationManager<JsonWebKeySet> wiring (no network yet)
    Host->>Cfg: read CorsConfig:AllowedOrigins, CorsConfig:AllowAnyOrigin
    Host->>Cfg: CorsConfigurationValidator.EnsureSafeForEnvironment — throws in Production when origins=[] AND allowAnyOrigin=false
    Host->>DI: register CORS policy (permissive OR WithOrigins(...))
    Host->>DI: register controllers + middleware + scoped AppDataConnection + scoped services
    Host->>DI: build Host
    Host->>Migrator: scope.Resolve<AppDataConnection>(); Migrate(db)
    Migrator->>DB: CREATE TABLE IF NOT EXISTS vehicles (...)
    Migrator->>DB: CREATE TABLE IF NOT EXISTS missions (...)
    Migrator->>DB: CREATE TABLE IF NOT EXISTS waypoints (...)
    Migrator->>DB: CREATE TABLE IF NOT EXISTS map_objects (...)
    Migrator->>DB: CREATE INDEX IF NOT EXISTS ix_missions_vehicle_id, ix_waypoints_mission_id, ix_map_objects_mission_id
    Migrator->>DB: DROP TABLE IF EXISTS orthophotos
    Migrator->>DB: DROP TABLE IF EXISTS gps_corrections
    note right of Migrator: B9 one-shot. Idempotent on devices that already cleaned up.
    Migrator-->>Host: void
    Host->>Host: emit PermissiveDefaultWarning if implicit-permissive CORS applies (non-Production with empty origins)
    Host->>Host: register ErrorHandlingMiddleware FIRST in pipeline
    Host->>Host: UseCors / UseAuthentication / UseAuthorization
    Host->>Host: MapControllers + MapGet("/health") + UseSwagger
    Host->>Docker: app.Run() — listening on 0.0.0.0:8080

Flowchart

flowchart TD
    Start([Container start]) --> ResolveDB[ResolveRequiredOrThrow DATABASE_URL]
    ResolveDB --> ResolveJwt["ResolveRequiredOrThrow JWT_ISSUER, JWT_AUDIENCE, JWT_JWKS_URL"]
    ResolveJwt --> CorsCfg[Read CorsConfig:AllowedOrigins + CorsConfig:AllowAnyOrigin]
    CorsCfg --> CorsGate{Production AND origins=[] AND allowAnyOrigin=false?}
    CorsGate -->|yes| FailFast([InvalidOperationException — Watchtower restarts])
    CorsGate -->|no| RegDI[DI registrations: JWT bearer + JWKS manager, CORS, controllers, scoped DB + services]
    RegDI --> Build[Build Host]
    Build --> CorsWarn{Implicit-permissive CORS in this env?}
    CorsWarn -->|yes| LogWarn[Log PermissiveDefaultWarning]
    CorsWarn -->|no| OpenScope[Open startup scope]
    LogWarn --> OpenScope
    OpenScope --> Migrate[Run DatabaseMigrator.Migrate]
    Migrate --> Create["CREATE TABLE IF NOT EXISTS x4 + indexes"]
    Create --> Drop["DROP TABLE IF EXISTS orthophotos, gps_corrections (B9)"]
    Drop --> Pipeline[Wire pipeline: error MW first, auth, controllers, /health, Swagger]
    Pipeline --> Run([app.Run on :8080])
    ResolveDB -. on missing value .-> FailFast
    ResolveJwt -. on missing value .-> FailFast
    Migrate -. on failure .-> Crash([Process exits non-zero — Watchtower restarts])

Data Flow

Step	From	To	Data	Format
1	Environment / IConfiguration	Program.cs (via ConfigurationResolver)	DATABASE_URL, JWT_ISSUER, JWT_AUDIENCE, JWT_JWKS_URL	string (required)
2	Environment / IConfiguration	Program.cs	CorsConfig:AllowedOrigins (string[]), CorsConfig:AllowAnyOrigin (bool)	optional
3	Program.cs	DI container	service registrations + JWT bearer + JWKS ConfigurationManager	C# code
4	DatabaseMigrator	postgres-local	DDL statements (CREATE / INDEX / DROP)	SQL
5	Program.cs	OS / Docker	bind to 0.0.0.0:8080	TCP listener

Error Scenarios

Error	Where	Detection	Recovery
Missing DATABASE_URL / JWT_ISSUER / JWT_AUDIENCE / JWT_JWKS_URL	ConfigurationResolver.ResolveRequiredOrThrow	env var + config key both empty/whitespace	Process exits non-zero with InvalidOperationException whose message names the missing env var and config key. Watchtower restarts but the new container hits the same failure. Fix: provide the value via env or appsettings.json
CORS misconfigured in Production (CorsConfig:AllowedOrigins=[] AND CorsConfig:AllowAnyOrigin!=true)	CorsConfigurationValidator.EnsureSafeForEnvironment at startup	hard-fail guard	Process exits with InvalidOperationException("CORS is misconfigured: ..."). Fix: set CorsConfig:AllowedOrigins to the production UI origins, or set CorsConfig:AllowAnyOrigin=true to opt in explicitly
postgres-local unreachable	Migrate step	Npgsql IOException / SocketException	Process exits non-zero. Watchtower restarts; flight-gate prevents restart mid-mission. Fix: ensure postgres-local healthcheck passes before missions starts (compose depends_on with condition: service_healthy)
azaion database missing	Migrate step	Npgsql 3D000 (invalid_catalog_name)	Process exits. Operator must create the database — provisioning concern, not this service. Documented in ../../suite/_docs/00_top_level_architecture.md
DROP TABLE IF EXISTS orthophotos fails because table is locked by gps-denied	B9 one-shot	Lock timeout or 55006	Process exits, Watchtower restarts in a few seconds. Out-of-band ordering: deploy gps-denied FIRST so it has its own copy of the schema before missions drops the legacy tables. Documented in B9 ticket
One CREATE TABLE succeeds, the next fails	Mid-Migrate	Npgsql exception on later statement	Process exits. Each statement is individually idempotent (IF NOT EXISTS) so the next startup retries safely from the start. No partial-migration cleanup needed
Wrong PostgreSQL version (e.g., < 13)	Migrate step	Specific syntax errors in newer features	Process exits. Suite-supported version is PG 16+; older devices need a Postgres upgrade
DATABASE_URL malformed (e.g. user password contains @)	ConvertPostgresUrl	parse failure / silent mis-parse	ConvertPostgresUrl does NOT URL-decode user/password — caveat for credentials with @, :, /, %. 07_host Caveats. Mitigation: avoid those chars in passwords, OR pass a raw Npgsql key=value string instead of a URL

Performance Expectations

Metric	Target	Notes
Cold start total time	<2 seconds typical on Jetson Orin	Migrator runs ~10 DDL statements; all are no-ops on a steady-state device
Cold start with legacy GPS-Denied tables present	+1 second	First-time-on-device B9 DROP adds two DDL statements
Crash recovery (Watchtower restart)	~10 seconds	Container restart latency dominates