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</content>
<parameter name="filePath">/home/jamesp/docker/pprdev/FLIGHT_STATE_FLOWS.md