Aviation Performance Management System

Comprehensive system for calculating transport potential and efficiency indicators for aviation operations, based on scientific research.

Features

Core Capabilities: Transport potential calculations (PT, Dopt, optimal payloads), cargo/passenger efficiency indicators, network opportunities, mission planning, aircraft management

Architecture: FastAPI backend (core formulas, calculator services, REST API), React frontend (dashboard, calculators, charts), PostgreSQL + TimescaleDB database, Redis caching

Prerequisites

Docker and Docker Compose (required) | Python 3.11+ (optional, for local development) | Node.js 18+ (optional, for frontend development)

Quick Start

Using Docker Compose (Recommended)

git clone <repository-url>
cd aviation-performance-management
cp .env.example .env  # Edit with your configuration
docker-compose up -d
docker-compose exec backend python scripts/seed_demo_data.py  # First time only

Access: Frontend http://localhost:5173 | Backend http://localhost:8000 | API Docs http://localhost:8000/api/docs

Local Development

Backend:

cd backend
python3.11 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
docker-compose up -d postgres redis  # Databases only
alembic upgrade head
python scripts/seed_demo_data.py  # Optional
uvicorn app.main:app --reload

Frontend:

cd frontend
npm install
npm run dev

Configuration

Copy .env.example to .env and set required secrets: POSTGRES_PASSWORD, SECRET_KEY, JWT_SECRET_KEY (min 32 chars). Generate: openssl rand -hex 32. See .env.example for all options.

Development

Testing: Backend cd backend && pytest | Frontend cd frontend && npm test Code Quality: Backend black app tests && isort app tests && mypy app && flake8 app tests | Frontend npm run lint && npm run format Database Migrations: Create alembic revision --autogenerate -m "..." | Apply alembic upgrade head | Rollback alembic downgrade -1

API Documentation

Interactive docs (when backend running): Swagger http://localhost:8000/api/docs | ReDoc http://localhost:8000/api/redoc | OpenAPI JSON http://localhost:8000/api/openapi.json

Technology Stack

Backend: Python 3.11, FastAPI, SQLAlchemy 2.0, PostgreSQL 15 + TimescaleDB, Redis | Frontend: React 18, TypeScript, Vite, TanStack Query, Zustand, Recharts | DevOps: Docker/Podman, pytest, Playwright

See CLAUDE.md for complete details and project structure.

Contributing

1. Create feature branch from main
2. Make changes and write/update tests
3. Ensure tests pass and code quality checks pass
4. Submit pull request

License

MIT License - See LICENSE file for details

References

Implements algorithms from aviation performance research. See aviation-performance-management-specification.md for formula references and CLAUDE.md for implementation guidance.