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
• Cache: Redis 7
• Container: Docker & Docker Compose

Features

• 🚀 Modern API: RESTful API with automatic OpenAPI documentation
• 🔐 Authentication: JWT-based authentication system with role-based access
• <EFBFBD> Transactional Email: SMTP-based email notifications for PPR submissions and cancellations
• <EFBFBD>📊 Real-time Updates: WebSocket support for live tower updates
• <EFBFBD> Comprehensive Reporting: Advanced reporting with filtering, search, and CSV/XLS export
• <EFBFBD>🗄️ 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

1. Start the System

cd nextgen
./start.sh

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: ppr_password123)
• phpMyAdmin: http://localhost:8083

3. Default Login

• Username: admin
• Password: admin123

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

# View logs
docker-compose logs -f api
docker-compose logs -f db

# Restart services
docker-compose restart

Testing

cd backend
pytest tests/

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
• Redis caching (ready for implementation)
• 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