✈️ AeroFlow

Aviation Safety & Risk Intelligence Platform
Real-time flight dispatch, ground operations, and safety management

⚠️ Project Under Construction

AeroFlow is actively being developed. Core functionality is implemented and ready for manual testing, but some features are still being built out. Expect breaking changes. Contributions and feedback are welcome.

Overview

AeroFlow is a production-oriented aviation safety and risk intelligence web application designed for managing flight dispatch operations, ground crew readiness, weather monitoring, and safety compliance. It enforces strict role-based access control, immutable audit logging, and real-time event streaming to ensure operational integrity.

Key Features

Flight Dispatch Management — Schedule, approve, and track flight dispatch operations with multi-gate safety enforcement.
Risk Calculation Engine — Weighted risk scoring based on crew fatigue, weather severity, equipment status, and checklist compliance.
Ground Operations Dashboard — Mobile-first interface for ground crew to complete pre-flight checklists and log shift fatigue.
Real-Time Alerts (SSE) — Server-Sent Events powered by a Node EventEmitter for live dispatch status updates.
Weather Ingestion — Automated weather data collection from OpenWeatherMap via Vercel Cron jobs.
AI Safety Drafts — LLM-powered draft safety briefings (clearly marked as drafts, never authoritative).
Immutable Audit Ledger — Every mutation is logged with user ID, action, resource, old/new state, timestamp, and IP address.
Manual Override System — Operations Directors can force-approve blocked flights with mandatory justification tracking.

Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router)
Language	TypeScript (strict mode)
Styling	TailwindCSS 4 (mobile-first)
Database	PostgreSQL
ORM	Prisma 6
Authentication	NextAuth.js v4 (Credentials Provider)
Validation	Zod
Live Updates	Server-Sent Events (SSE)
Weather API	OpenWeatherMap
AI Drafting	OpenAI API (gpt-4o-mini)
Deployment	Vercel
Scheduled Jobs	Vercel Cron
Testing	Vitest

Architecture

┌──────────────────────────────────────────────────────┐
│                    Next.js App Router                │
│  ┌──────────┐  ┌───────────┐  ┌──────────────────┐   │
│  │  Pages   │  │  Layouts  │  │   API Routes     │   │
│  │ (RSC)    │  │ (Auth)    │  │ /auth /cron /sse │   │
│  └────┬─────┘  └─────┬─────┘  └────────┬─────────┘   │
│       │              │                 │             │
│  ┌────▼──────────────▼─────────────────▼──────────┐  │
│  │              Server Actions                    │  │
│  │   flight.ts  ·  crew.ts  ·  actions.ts         │  │
│  └────────────────────┬───────────────────────────┘  │
│                       │                              │
│  ┌────────────────────▼───────────────────────────┐  │
│  │              Core Libraries                    │  │
│  │   risk.ts · auth.ts · ai.ts · events.ts        │  │
│  │   audit/ledger.ts · db.ts · validations.ts     │  │
│  └────────────────────┬───────────────────────────┘  │
│                       │                              │
│  ┌────────────────────▼───────────────────────────┐  │
│  │          Prisma ORM → PostgreSQL               │  │
│  └────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────┘

Prerequisites

Before you begin, ensure you have the following installed:

Node.js ≥ 18.17 — Download
npm ≥ 9 (ships with Node.js)
PostgreSQL ≥ 14 — Download
Git — Download
A Vercel account (for deployment) — Sign up

Getting Started

1. Fork & Clone

Fork the repository on GitHub by clicking the "Fork" button at the top right of the repo page.

Then clone your fork locally:

git clone https://github.com/<your-username>/AeroFlow.git
cd AeroFlow

2. Install Dependencies

npm install

This will install all runtime and development dependencies including Next.js, Prisma, NextAuth, Zod, and TailwindCSS.

3. Environment Variables

Create a .env file in the project root. This file is git-ignored by default and must never be committed.

cp .env.example .env

Or create it manually with the following variables:

# ─── Database ────────────────────────────────────────
DATABASE_URL="postgresql://<user>:<password>@localhost:5432/aeroflow?schema=public"

# ─── NextAuth ────────────────────────────────────────
NEXTAUTH_SECRET="your-random-secret-string-here"
NEXTAUTH_URL="http://localhost:3000"

# ─── External APIs ───────────────────────────────────
OPENWEATHER_API_KEY="your-openweathermap-api-key"
OPENAI_API_KEY="your-openai-api-key"

# ─── Cron Protection ────────────────────────────────
CRON_SECRET="your-cron-secret-string"

Variable	Required	Description
`DATABASE_URL`	✅	PostgreSQL connection string
`NEXTAUTH_SECRET`	✅	Random string for JWT signing (generate one)
`NEXTAUTH_URL`	✅	Your app's base URL (`http://localhost:3000` for local dev)
`OPENWEATHER_API_KEY`	✅	Free API key from OpenWeatherMap
`OPENAI_API_KEY`	⚠️	Required only for AI safety draft generation
`CRON_SECRET`	✅	Bearer token to protect the weather cron endpoint

4. Database Setup

Create the PostgreSQL database:

createdb aeroflow

Generate the Prisma client and push the schema to your database:

npx prisma generate
npx prisma db push

Note: prisma db push is used for development. For production migrations, use npx prisma migrate dev to create a migration history.

Seed initial data (optional):

If a seed file exists:

npx prisma db seed

If no seed file exists yet, you can manually insert a test user via Prisma Studio:

npx prisma studio

This opens a browser UI at http://localhost:5555 where you can create users with different roles (GROUND_CREW_LEAD, FLIGHT_DISPATCHER, OPERATIONS_DIRECTOR).

5. Run the Dev Server

npm run dev

Open http://localhost:3000 in your browser.

Deployment to Vercel

1. Push to GitHub

If you haven't already, initialize git and push to your fork:

git add .
git commit -m "Initial commit"
git push origin main

2. Connect to Vercel

Go to vercel.com/new.
Import your GitHub repository.
Select the Next.js framework preset (should be auto-detected).

3. Configure Environment Variables

In the Vercel project dashboard, navigate to Settings → Environment Variables and add each variable from your .env file:

Key	Value	Environment
`DATABASE_URL`	Your hosted PostgreSQL connection string (e.g., from Neon, Supabase, or Railway)	Production, Preview
`NEXTAUTH_SECRET`	Your secret string	Production, Preview
`NEXTAUTH_URL`	`https://your-app.vercel.app`	Production
`OPENWEATHER_API_KEY`	Your API key	Production, Preview
`OPENAI_API_KEY`	Your API key	Production, Preview
`CRON_SECRET`	Your cron secret	Production, Preview

Important: You must use a hosted PostgreSQL provider for Vercel deployment. Vercel serverless functions cannot connect to localhost.

4. Configure Cron Jobs

Create or verify the vercel.json file in the project root:

{
  "crons": [
    {
      "path": "/api/cron/weather",
      "schedule": "*/15 * * * *"
    }
  ]
}

This runs the weather ingestion cron every 15 minutes. The endpoint is protected by the CRON_SECRET bearer token — Vercel automatically sends the Authorization: Bearer <CRON_SECRET> header for cron invocations.

5. Deploy

After pushing and configuring environment variables:

git push origin main

Vercel will automatically build and deploy. You can also trigger a manual deploy from the Vercel dashboard.

Post-deployment checklist:

Run npx prisma db push against your production database (or apply migrations)
Verify the app loads at your Vercel URL
Create initial users via Prisma Studio connected to your production DB
Test the authentication flow

Manual Testing Guide

Follow these steps to verify the complete dispatch flow:

Step 1 — Create Test Users

Use Prisma Studio or a database client to insert users with these roles:

Email	Role
`crew@aeroflow.test`	`GROUND_CREW_LEAD`
`dispatcher@aeroflow.test`	`FLIGHT_DISPATCHER`
`director@aeroflow.test`	`OPERATIONS_DIRECTOR`

Step 2 — Create a Flight

Insert a Flights record with status SCHEDULED, linked to a RouteProfiles entry and at least one FlightChecklists with mandatory ChecklistItems.

Step 3 — Ground Operations

Log in as crew@aeroflow.test.
Navigate to /crew/dashboard.
Complete all mandatory checklist items by clicking the checkboxes.
Submit a shift log with a fatigue score.

Step 4 — Dispatch Approval

Log in as dispatcher@aeroflow.test.
Navigate to /dispatcher/dashboard.
Click into a flight to view its dossier at /dispatcher/flight/[id].
Verify the risk score, weather status, and checklist completion are displayed.
Click Approve Dispatch (should succeed if risk is below critical threshold).

Step 5 — Test Blocked Dispatch

Create a scenario with high fatigue (index > 8) or critical weather.
Verify the Approve Dispatch button is disabled and an error is thrown.

Step 6 — Manual Override

Log in as director@aeroflow.test.
Navigate to the blocked flight's dossier.
Enter a justification and click Force Override.
Verify the flight status changes to READY.

Step 7 — Audit Verification

Log in as director@aeroflow.test.
Navigate to /director/ledger.
Verify all actions (checklist completions, shift logs, approvals, overrides) are logged with correct timestamps, user IDs, and IP addresses.

Project Structure

AeroFlow/
├── prisma/
│   └── schema.prisma          # Database schema (20+ models)
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   ├── auth/[...nextauth]/  # NextAuth API route
│   │   │   ├── cron/weather/        # Weather ingestion cron
│   │   │   └── sse/                 # Server-Sent Events endpoint
│   │   ├── crew/
│   │   │   └── dashboard/           # Ground operations UI
│   │   ├── dispatcher/
│   │   │   ├── dashboard/           # Dispatch overview
│   │   │   └── flight/[id]/         # Flight dossier & approval
│   │   ├── director/
│   │   │   └── ledger/              # Immutable audit log viewer
│   │   ├── layout.tsx               # Root layout
│   │   ├── page.tsx                 # Landing page
│   │   └── globals.css              # Global styles
│   └── lib/
│       ├── actions/
│       │   ├── crew.ts              # Checklist & shift log actions
│       │   └── flight.ts            # Dispatch approval & override
│       ├── audit/
│       │   └── ledger.ts            # Immutable audit logging
│       ├── auth.ts                  # NextAuth config & RBAC
│       ├── ai.ts                    # OpenAI draft generation
│       ├── db.ts                    # Prisma client singleton
│       ├── events.ts                # SSE EventEmitter singleton
│       ├── risk.ts                  # Risk calculation engine
│       └── validations.ts           # Zod schemas
├── tests/
│   └── unit/
│       └── risk.test.ts             # Risk engine unit tests
├── .env                             # Environment variables (git-ignored)
├── .gitignore
├── package.json
├── tsconfig.json
├── next.config.ts
├── postcss.config.mjs
├── eslint.config.mjs
└── README.md

API Routes

Route	Method	Auth	Description
`/api/auth/[...nextauth]`	GET/POST	Public	NextAuth authentication endpoints
`/api/cron/weather`	GET	Bearer Token (`CRON_SECRET`)	Ingests weather data for active flights
`/api/sse`	GET	None (event stream)	Real-time Server-Sent Events for dispatch updates

Roles & Permissions

Role	Access
`GROUND_CREW_LEAD`	`/crew/dashboard` — Complete checklists, log shift fatigue
`FLIGHT_DISPATCHER`	`/dispatcher/dashboard`, `/dispatcher/flight/[id]` — View flights, approve dispatch
`OPERATIONS_DIRECTOR`	All dispatcher routes + `/director/ledger` — Override blocked dispatches, view audit logs

Running Tests

Run the Vitest test suite:

npx vitest run

Run tests in watch mode:

npx vitest

Run a specific test file:

npx vitest run tests/unit/risk.test.ts

Contributing

Fork the repository.
Create a feature branch: git checkout -b feature/your-feature-name
Commit your changes: git commit -m "feat: add your feature"
Push to your branch: git push origin feature/your-feature-name
Open a Pull Request against the main branch.

Contribution Guidelines

Follow TypeScript strict mode — no any types except where explicitly required.
All Server Actions must include requireRole() and logAudit() calls.
Never expose API keys or secrets to client components.
Write tests for any new risk calculation logic or gating rules.
Use conventional commit messages (feat:, fix:, docs:, test:).

License

This project is currently unlicensed. A license will be added as the project matures.

⚠️ Project Under Construction ⚠️
AeroFlow is being actively developed. Features, APIs, and database schemas may change without notice.

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
prisma		prisma
public		public
src		src
tests/unit		tests/unit
.git-old-live-flights.txt		.git-old-live-flights.txt
.gitignore		.gitignore
AGENTS.md		AGENTS.md
README.md		README.md
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
supabase_schema.sql		supabase_schema.sql
test-db.js		test-db.js
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation