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

Flow F4 — Waypoint create / read / update / delete

Post-rename / post-B7. Waypoint delete is a scoped variant of F3's cross-service cascade — same NO-transaction caveat applies (architecture.md ADR-006).

Description

Waypoint CRUD nested under a mission (/missions/{id}/waypoints/*). Read-list is unpaginated by spec, ordered by OrderNum. UpdateWaypoint is a full overwrite of every field even though the request DTO looks "partial-shaped" (see 02_mission_planning Caveats #2). Delete walks the cross-service cascade for one waypoint (compare F3 which walks for ALL waypoints of a mission).

Preconditions

• Parent mission exists (KeyNotFoundException → 404 otherwise on every endpoint).
• Caller holds JWT with permissions=FL (F5).
• Schema in place for borrowed tables (media, annotations, detection) for delete.

Sequence Diagram (DELETE one waypoint)

sequenceDiagram
    autonumber
    participant UI as Operator UI
    participant Identity as 05_identity
    participant Ctrl as MissionsController
    participant WS as WaypointService
    participant DB as 04_persistence (postgres-local)
    participant Annot as [[annotations service schema]]
    participant Det as [[detection pipeline schema]]

    UI->>Identity: DELETE /missions/{id}/waypoints/{wpId} + JWT
    Identity-->>Ctrl: authorized (policy "FL")
    Ctrl->>WS: DeleteWaypoint(missionId, wpId)
    WS->>DB: SELECT 1 FROM waypoints WHERE mission_id=? AND id=?
    alt Not found
        DB-->>WS: 0 rows
        WS-->>UI: 404 Not Found
    else Found
        WS->>Annot: SELECT id FROM media WHERE waypoint_id = ? → mediaIds
        WS->>Annot: SELECT id FROM annotations WHERE media_id IN ? → annotationIds
        WS->>Det: DELETE FROM detection WHERE annotation_id IN annotationIds
        WS->>Annot: DELETE FROM annotations WHERE id IN annotationIds
        WS->>Annot: DELETE FROM media WHERE id IN mediaIds
        WS->>DB: DELETE FROM waypoints WHERE id = ?
        WS-->>UI: 204 No Content
    end

Flowchart (PUT — full overwrite)

flowchart TD
    Start([PUT /missions/id/waypoints/wpId + body]) --> Auth{JWT + FL valid?}
    Auth -->|no| Reject([401 / 403])
    Auth -->|yes| Lookup[SELECT * FROM waypoints WHERE mission_id=? AND id=?]
    Lookup --> Exists{Found?}
    Exists -->|no| NotFound([404])
    Exists -->|yes| Overwrite["UPDATE waypoints SET lat=?, lon=?, mgrs=?, alt=?, source=?, objective=?, order_num=?, name=? WHERE id=?"]
    Overwrite --> Done([200 OK + Waypoint])
    note1[NOTE: Sending partial body zeroes out missing numeric fields and resets enums to default 0. Spec uses Geopoint type with auto-conversion; code uses 3 flat fields. Carry-forward.]

Data Flow

Step	From	To	Data	Format
1	UI	MissionsController (nested)	mission id + waypoint id (URL) + CreateWaypointRequest / UpdateWaypointRequest body	path params + JSON
2	WaypointService	waypoints table	INSERT / UPDATE / SELECT / DELETE	SQL
3	WaypointService	media / annotations / detection (delete only)	SELECT id then DELETE WHERE id IN (...)	SQL
4	WaypointService	UI	Waypoint entity / List<Waypoint> / 204	JSON (PascalCase)

Error Scenarios

Error	Where	Detection	Recovery
Parent mission not found	Service entity lookup	null	KeyNotFoundException → 404
Waypoint not found in mission	Service entity lookup with both ids	null	KeyNotFoundException → 404
PUT zeroes out coordinates	WaypointService.UpdateWaypoint	None	Body intent is "partial" but code overwrites every column → silent data loss for missing fields. Carry-forward (02_mission_planning Caveats #2)
Race on N waypoints reordered as N PUTs	Caller-side	None	No reorder endpoint exists — caller must coordinate; partially-applied reorders leave inconsistent order_nums (02_mission_planning Caveats #5)
Delete cascade relation does not exist for media / annotations / detection	DELETE steps	Npgsql PostgresException (42P01)	500. Same diagnosis as F3: abnormal edge deployment
Partial failure mid-delete-cascade	Same as F3	Npgsql exception	500 + orphan rows. ADR-006 carry-forward

Performance Expectations

Metric	Target	Notes
Create / read / update	<10ms typical	Single round-trip
List (unpaginated)	<30ms typical for ≤1000 waypoints	ix_waypoints_mission_id index used; sort by order_num is in-memory (no order index)
Delete (with cross-service cascade)	<30ms typical for ≤100 media rows per waypoint	5–6 round-trips