AirTrail

AirTrail is a self‑hosted, full‑stack web application designed to ingest, store, and visualise personal flight data. At its core, the system receives raw flight telemetry—typically in JSON or CSV from services such as MyFlightRadar24, App in the Air, or JetLog—parses it into a canonical schema, and persists it to a relational database. The front‑end consumes this data through a RESTful API, rendering an interactive world map (powered by Leaflet or Mapbox) and a timeline of flight events. The architecture is intentionally modular: the API layer, database access, authentication, and UI are decoupled behind clear interfaces, enabling developers to replace or extend any component without touching the rest of the stack.

• Backend: Implemented in TypeScript using NestJS, which provides a structured module system and dependency injection. The service layer encapsulates business logic for flight ingestion, user management, and statistics calculation.
• Database: PostgreSQL serves as the primary datastore. The schema is normalized with a flights table, a users table, and supporting tables for OAuth credentials. TypeORM or Prisma is used as the ORM to map entities to SQL, enabling migrations and query optimization.
• Authentication: JWT‑based sessions are combined with OAuth 2.0 support, allowing integration with external identity providers (Google, GitHub, etc.). Role‑based access control is enforced at the controller level.
• Front‑end: A SPA built with Vue 3 (or React, depending on the branch) and Vite. The UI is responsive, with a dark/light theme toggle stored in local storage. Map interactions use the Leaflet library, while statistical charts are rendered with Chart.js or D3.
• Containerization: A Dockerfile exposes port 3000 for the API and a separate container for the database (PostgreSQL). Docker Compose orchestrates the stack, providing environment variables for secrets and network isolation.

• Flight Import API: Endpoints like /api/import accept multipart uploads of CSV/JSON, triggering background workers that parse and validate the payload before persisting.
• Realtime Map Streaming: WebSocket or Server‑Sent Events (SSE) streams allow the UI to receive live updates when a new flight is added or an existing one is edited.
• Statistics Service: Aggregates metrics such as total distance, average speed, and most frequent routes. These are exposed via /api/stats and can be consumed by external dashboards.
• Webhooks: External services can subscribe to events (e.g., flight.created) via a webhook endpoint, enabling integrations with CI/CD pipelines or monitoring tools.
• Extensibility Hooks: The import pipeline exposes hooks (onBeforeImport, onAfterImport) that developers can override to implement custom validation or enrichment logic.

AirTrail is designed for simplicity: a single docker-compose.yml file pulls the latest image from Docker Hub (johly/airtrail) and mounts a data volume for PostgreSQL persistence. For production, the image can be deployed behind an Nginx reverse proxy with HTTPS termination (e.g., via Traefik). The application scales horizontally by running multiple API instances behind a load balancer; PostgreSQL can be replicated using streaming replication or managed services like RDS. The lightweight container footprint (under 200 MB) and stateless API design make it ideal for Kubernetes or serverless platforms such as AWS Fargate.

• Plugin Architecture: AirTrail exposes a plugin registry where developers can register custom modules that hook into the import lifecycle or UI components. This allows adding support for new data sources (e.g., ADS‑B exchange) without modifying the core codebase.
• OAuth Provider Integration: By configuring OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET, any OpenID‑Connect provider can be used for single‑sign‑on, making it straightforward to embed AirTrail into existing corporate identity ecosystems.
• API Documentation: Swagger/OpenAPI is auto‑generated from NestJS decorators, providing interactive docs at /docs. This facilitates rapid prototyping of third‑party clients.

The project follows industry best practices: linting with ESLint, type safety via TypeScript, and CI pipelines that run tests, SonarCloud analysis, and Docker image builds. The documentation is hosted at https://airtrail.johan.ohly.dk/docs, covering everything from architecture diagrams to API reference. Community support is active on GitHub Discussions, and the open‑source license (MIT) removes any commercial barriers. The codebase is modular enough that contributors can focus on a single feature (e.g., adding a new statistic) without needing to understand the entire stack.

• Personal Aviation Enthusiasts: Track and archive every flight, generate trip logs, and share itineraries with friends.
• Flight Clubs & Schools: Manage a fleet of aircraft, monitor pilot progress, and produce compliance reports.
• Aviation Analytics: Integrate AirTrail’s API into a larger analytics platform to correlate flight data with weather or airspace usage.
• IoT Device Deployments: Use the import API to ingest telemetry from custom flight trackers and display it in real time on a web dashboard.

• Open Source & Self‑Hosted: Full control over data privacy and compliance with GDPR or