ppr-ng/FLIGHT_STATE_FLOWS.md

Flight State Flow Documentation

This document describes the state flows for each flight type in the PPR system.

Overview

The system manages different types of aircraft operations, each with their own state machines and status transitions. The main flight types are:

1. Circuits - Touch-and-go circuit training flights
2. Local Flights - General local operations
3. Inbound/Arrivals - Aircraft arriving at the airport
4. Departures - Aircraft departing to other airports
5. PPR Records - Prior permission required advance bookings
6. Overflights - Aircraft passing through airspace

1. Circuits

Circuits are a special type of local flight where aircraft perform touch-and-go operations. The circuit system tracks individual circuit completions.

State Flow

BOOKED_OUT → DEPARTED → LANDED
     ↓         ↓         ↓
 CANCELLED  CANCELLED  CANCELLED

Status Descriptions

• BOOKED_OUT: Flight is booked out and ready for departure
• DEPARTED: Aircraft has departed the airport
• LANDED: Aircraft has landed and flight is complete
• CANCELLED: Flight was cancelled before completion

Additional Features

• Individual circuit timestamps are recorded in the circuits table
• The circuits field on the local_flight record stores the total number of completed circuits
• Circuits are counted automatically when the flight status changes to LANDED

2. Local Flights

Local flights represent general aviation operations within the local area.

State Flow

BOOKED_OUT → DEPARTED → LANDED
     ↓         ↓         ↓
 CANCELLED  CANCELLED  CANCELLED

Status Descriptions

• BOOKED_OUT: Flight is booked out and ready for departure
• DEPARTED: Aircraft has departed the airport
• LANDED: Aircraft has landed and flight is complete
• CANCELLED: Flight was cancelled before completion

Flight Types

Local flights can be categorized by their flight_type:

• LOCAL: Standard local flight
• CIRCUITS: Circuit training flight (see Circuits section above)
• DEPARTURE: Flight departing to another airport (may transition to Departure records)

3. Inbound/Arrivals

Inbound flights are aircraft arriving at the airport, either through the PPR system or direct bookings.

State Flow

BOOKED_IN → LANDED
     ↓         ↓
 CANCELLED  CANCELLED

Status Descriptions

• BOOKED_IN: Aircraft is expected to arrive (booked in the system)
• LANDED: Aircraft has landed at the airport
• CANCELLED: Arrival was cancelled

Notes

• Arrivals can originate from PPR records that have landed
• Direct arrival bookings are also supported
• Landing timestamp is recorded when status changes to LANDED

4. Departures

Departures are aircraft leaving the airport to fly to other destinations.

State Flow

BOOKED_OUT → DEPARTED
     ↓         ↓
 CANCELLED  CANCELLED

Status Descriptions

• BOOKED_OUT: Flight is booked out and ready for departure
• DEPARTED: Aircraft has departed to its destination
• CANCELLED: Departure was cancelled

Notes

• Departures can originate from PPR records that are departing
• Local flights with flight_type = DEPARTURE may transition to departure records
• Departure timestamp is recorded when status changes to DEPARTED

5. PPR (Prior Permission Required) Records

PPR records represent advance permission requests for aircraft operations and have a more complex lifecycle.

State Flow

   NEW → CONFIRMED → LANDED → DEPARTED
     ↓         ↓         ↓         ↓
  CANCELED   CANCELED   CANCELED   (terminal)
     ↓
  DELETED

Status Descriptions

• NEW: PPR has been submitted but not yet confirmed
• CONFIRMED: PPR has been confirmed by ATC
• LANDED: Aircraft has landed (for inbound operations)
• DEPARTED: Aircraft has departed (for outbound operations)
• CANCELED: PPR was cancelled
• DELETED: PPR was soft-deleted (marked as deleted)

Notes

• PPRs can represent both arrivals and departures
• The system tracks both ETA (Estimated Time of Arrival) and ETD (Estimated Time of Departure)
• Timestamps are recorded for actual landing and departure times
• PPRs can transition between arrival and departure operations

6. Overflights

Overflights represent aircraft passing through the airspace without landing at the airport.

State Flow

ACTIVE → INACTIVE
   ↓         ↓
CANCELLED CANCELLED

Status Descriptions

• ACTIVE: Overflight is currently active/tracking
• INACTIVE: Overflight has completed or is no longer active
• CANCELLED: Overflight was cancelled

Notes

• Overflights track aircraft that call in for frequency changes (QSY)
• Call time and QSY time are recorded
• Overflights are typically managed separately from landing operations

Status Transition Rules

Automatic Transitions

• Status changes automatically set appropriate timestamps:
  • DEPARTED: Sets departed_dt
  • LANDED: Sets landed_dt
  • For circuits: Also counts completed circuits

Manual Transitions

• Operators can manually update statuses through the admin interface
• Status changes are logged in the journal/audit trail
• WebSocket notifications are sent for real-time updates

Validation Rules

• Cannot transition backwards in the flow (e.g., from LANDED to DEPARTED)
• CANCELLED/CANCELED are terminal states for most flight types
• DELETED is only used for PPR soft-deletion
• Status enum values: Most use "CANCELLED", PPR uses "CANCELED"

Integration Points

UI Integration

• Admin interface provides buttons for status updates
• Real-time updates via WebSocket
• Modal dialogs for status changes with timestamp confirmation

API Integration

• REST endpoints for status updates: PATCH /{id}/status
• Status filtering available on list endpoints
• Journal logging for all status changes

Database Integration

• Status enums ensure data integrity
• Foreign key relationships maintain consistency
• Audit trail tracks all changes /home/jamesp/docker/pprdev/FLIGHT_STATE_FLOWS.md