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
- � **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):**
```bash
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:**
```bash
docker compose logs -f api
```

### Production Deployment

**Simple automated deployment:**

```bash
# 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 (4 workers)

**Monitor deployment:**
```bash
docker compose -f docker-compose.prod.yml logs -f api
```

**Deploying updates with migrations:**
```bash
git pull
docker compose -f docker-compose.prod.yml up -d --build
# Migrations apply automatically!
```

**See detailed guides:**
- [`AUTOMATED_MIGRATION_GUIDE.md`](./AUTOMATED_MIGRATION_GUIDE.md) - How automatic migrations work
- [`PRODUCTION_MIGRATION_GUIDE.md`](./PRODUCTION_MIGRATION_GUIDE.md) - Advanced migration strategies
- [`MIGRATION_QUICK_REF.md`](./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
```bash
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload
```

### Database Management
```bash
# 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
```bash
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:
```bash
# 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:

```bash
# 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

```bash
docker-compose down
```

To remove volumes (database data):
```bash
docker-compose down -v
```