ppr-ng/README.md

NextGen PPR System

A modern, containerized Prior Permission Required (PPR) system for aircraft operations management.

Architecture

• Backend: FastAPI with Python 3.11
• Database: MySQL 8.0
• Container: Docker & Docker Compose

Features

• 🚀 Modern API: RESTful API with automatic OpenAPI documentation
• 🔐 Authentication: JWT-based authentication system with role-based access
• � Transactional Email: SMTP-based email notifications for PPR submissions and cancellations
• �📊 Real-time Updates: WebSocket support for live tower updates
• � Comprehensive Reporting: Advanced reporting with filtering, search, and CSV/XLS export
• �🗄️ Self-contained: Fully dockerized with local database
• 🔍 Documentation: Auto-generated API docs at /docs
• 🧪 Testing: Comprehensive test suite with data population utilities
• 📱 Mobile Ready: Responsive design for tower operations
• 🔄 Public Forms: Enhanced public PPR submission and editing with intelligent field lookups
• 📋 Audit Trail: Complete journal system tracking all PPR changes

Quick Start

Prerequisites

• Docker and Docker Compose installed

Development Setup

Start the system (automatic database setup):

docker compose up -d

That's it! The container automatically:

• Waits for database to be ready
• Creates schema via Alembic migrations
• Loads airport and aircraft reference data
• Starts the API with auto-reload

View startup logs:

docker compose logs -f api

Production Deployment

Simple automated deployment:

# 1. Configure environment
cp .env.example .env
nano .env  # Set your external database credentials

# 2. Start with production settings
docker compose -f docker-compose.prod.yml up -d

The container automatically handles:

• Database connection verification
• Schema creation/migration (Alembic)
• Reference data seeding (if needed)
• Production server startup (single worker for in-process WebSocket broadcasts)

Monitor deployment:

docker compose -f docker-compose.prod.yml logs -f api

Deploying updates with migrations:

git pull
docker compose -f docker-compose.prod.yml up -d --build
# Migrations apply automatically!

See detailed guides:

• AUTOMATED_MIGRATION_GUIDE.md - How automatic migrations work
• PRODUCTION_MIGRATION_GUIDE.md - Advanced migration strategies
• MIGRATION_QUICK_REF.md - Quick reference commands

2. Access the Services

• API Documentation: http://localhost:8001/docs
• API Base URL: http://localhost:8001/api/v1
• Public Web Interface: http://localhost:8082
• Admin Interface: http://localhost:8082/admin.html
• Reports Interface: http://localhost:8082/reports.html
• Database: localhost:3307 (user: ppr_user, password: [configured in .env])
• phpMyAdmin: http://localhost:8083

3. Default Login

• Username: admin
• Password: [configured in database - see init_db.sql]

API Endpoints

Authentication

• POST /api/v1/auth/login - Login and get JWT token

PPR Management

• GET /api/v1/pprs - List PPR records (with filtering by status, date range)
• POST /api/v1/pprs - Create new PPR
• GET /api/v1/pprs/{id} - Get specific PPR
• PUT /api/v1/pprs/{id} - Update PPR
• PATCH /api/v1/pprs/{id} - Partially update PPR
• PATCH /api/v1/pprs/{id}/status - Update PPR status
• DELETE /api/v1/pprs/{id} - Delete PPR
• GET /api/v1/pprs/{id}/journal - Get PPR activity journal

Public Endpoints (No Auth Required)

• GET /api/v1/public/arrivals - Today's arrivals
• GET /api/v1/public/departures - Today's departures
• POST /api/v1/public/pprs - Submit public PPR
• GET /api/v1/public/edit/{token} - Get PPR for public editing
• PATCH /api/v1/public/edit/{token} - Update PPR publicly
• DELETE /api/v1/public/cancel/{token} - Cancel PPR publicly

User Management (Admin Only)

• GET /api/v1/auth/users - List users
• POST /api/v1/auth/users - Create user
• GET /api/v1/auth/users/{id} - Get user details
• PUT /api/v1/auth/users/{id} - Update user
• DELETE /api/v1/auth/users/{id} - Delete user

Reference Data

• GET /api/v1/airport/lookup/{code} - Lookup airport by ICAO code
• GET /api/v1/aircraft/lookup/{reg} - Lookup aircraft by registration

Real-time

• WebSocket /ws/tower-updates - Live updates for tower operations

Web Interfaces

Public PPR Forms

• URL: http://localhost:8082
• Features:
  • PPR submission form with intelligent aircraft/airport lookups
  • Date/time pickers with 15-minute intervals
  • Email notifications for submissions
  • Public editing/cancellation via secure tokens

Admin Interface

• URL: http://localhost:8082/admin.html
• Features:
  • Complete PPR management (CRUD operations)
  • Advanced filtering by status, date range
  • Inline editing with modal interface
  • Journal/audit trail viewing
  • Quick status updates (Confirm, Land, Depart, Cancel)
  • New PPR entry creation
  • User management (administrators only)
  • Real-time WebSocket updates

Reports Interface

• URL: http://localhost:8082/reports.html
• Features:
  • Comprehensive PPR reporting with date range filtering
  • Search across aircraft, captain, and airport fields
  • Status-based filtering
  • CSV and XLS export functionality
  • Responsive table with all PPR details

Development

Local Development

cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload

Database Management

# Connect to database
docker exec -it ppr_nextgen_db mysql -u ppr_user -p ppr_nextgen

# When prompted for password, use the value from .env (DB_PASSWORD)

Testing

The backend API tests use pytest, FastAPI's TestClient, and an isolated in-memory SQLite database with dependency overrides for database sessions and authenticated users.

See backend/tests/README.md for a module-by-module explanation of what the tests cover and why.

cd backend
pytest

Or, with the Docker development stack running:

docker compose exec api pytest

To inspect API test coverage:

cd backend
pytest --cov=app --cov-report=term-missing

Or in Docker:

docker compose exec api pytest --cov=app --cov-report=term-missing

End-to-End Testing

Browser e2e tests use pytest plus Playwright. The recommended path is the containerized runner, which joins the same Compose network as the app and opens the web service at http://web.

docker compose -f docker-compose.yml -f docker-compose.e2e.yml up -d db api web
docker compose -f docker-compose.yml -f docker-compose.e2e.yml run --rm e2e

Authenticated browser tests are skipped unless E2E_ADMIN_USERNAME and E2E_ADMIN_PASSWORD are supplied. See tests/e2e/README.md for credential examples, host-run instructions, and guidance for adding specs.

The e2e Compose override uses a separate MySQL container and volume, so tests do not use the normal dev/prod database configured in .env. It is still a real MySQL database, but isolated for e2e.

E2e reports are written to test-results/e2e-report.html and test-results/e2e-junit.xml.

Additional Features

Email Notifications

The system includes transactional email support for:

• PPR Submissions: Automatic email confirmation to submitters
• PPR Cancellations: Notification emails when PPRs are cancelled
• SMTP Configuration: Configurable SMTP settings via environment variables

Test Data Generation

A comprehensive test data population script is included:

# Generate test PPR records
docker exec -it ppr_nextgen_api python populate_test_data.py

# Or run the convenience script
./populate_test_data.sh

This creates diverse PPR records across all statuses with realistic aircraft and airport data for testing purposes.

Audit Trail

Complete activity logging system tracks:

• All PPR field changes with before/after values
• Status transitions with timestamps
• User actions and IP addresses
• Automatic journal entries for all modifications

Environment Variables

Key environment variables (configured in docker-compose.yml):

• DB_HOST - Database host
• DB_USER - Database username
• DB_PASSWORD - Database password
• DB_NAME - Database name
• SECRET_KEY - JWT secret key
• ACCESS_TOKEN_EXPIRE_MINUTES - Token expiration time

Email Configuration

• SMTP_SERVER - SMTP server hostname
• SMTP_PORT - SMTP server port (default: 587)
• SMTP_USERNAME - SMTP authentication username
• SMTP_PASSWORD - SMTP authentication password
• SMTP_TLS - Enable TLS (default: true)
• FROM_EMAIL - Sender email address
• BASE_URL - Base URL for email links

Database Schema

The system uses an improved version of the original schema with:

• users - User authentication
• submitted - PPR records with status tracking
• journal - Activity logs with foreign keys
• airports - Airport reference data
• aircraft - Aircraft registration database

Data Migration

To migrate data from the old system:

1. Export data from the old database
2. Transform to new schema format
3. Import into the new system

Time Zone Handling

The system uses UTC (Coordinated Universal Time) as the standard for all time storage and display in aviation contexts:

• Database Storage: All times are stored in UTC
• Admin Console Display: Times are displayed in UTC (with Z suffix)
• Data Entry: Times are entered as local time in the New PPR entry form, then automatically converted to UTC for storage
• API: All datetime fields in API responses are UTC ISO strings

This ensures consistency across different time zones and complies with aviation standards where UTC is the international standard.

Performance

• Database connection pooling
• Indexed columns for fast queries
• Async/await for non-blocking operations

Monitoring

Access logs and monitoring:

# View API logs
docker-compose logs -f api

# View database logs  
docker-compose logs -f db

# System health check
curl http://localhost:8001/health

Stopping the System

docker-compose down

To remove volumes (database data):

docker-compose down -v