Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js 20+ and pnpm 9.15.1+
  • PostgreSQL database
  • Redis server
  • Flutter SDK 3.6.0+ (for mobile development)
  • Bun (for scripts and tools)
You’ll also need API keys from FlightAware, AviationStack, and AeroDataBox (via RapidAPI) for flight data.

​
Setup the backend API

1

Clone and navigate to the API directory

cd api
pnpm install
2

Configure environment variables

Copy the example environment file and add your configuration:
cp .env.example .env
Edit .env with your settings:
DATABASE_URL="postgresql://user:password@localhost:5432/aero"
JWT_SECRET="your-secret-key-here"
AVIATION_STACK_API_KEY="your-aviation-stack-key"
RAPID_API_KEY="your-rapid-api-key"
FLIGHTAWARE_API_KEY="your-flightaware-key"
Keep your API keys secure and never commit them to version control.
3

Run database migrations

pnpm run prisma migrate dev
This sets up the database schema with tables for users, flights, airports, airlines, aircraft, and bookings.
4

Start the development server

pnpm run start:dev
The API will be available at:
  • API Server: http://localhost:3000
  • API Documentation: http://localhost:3000/docs
  • Scalar API Reference: http://localhost:3000/reference

​
Track your first flight

Now that your API is running, let’s track a flight using the REST endpoints.
1

Register a new user

curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securepassword",
    "name": "John Doe"
  }'
Response:
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "clx1234567890",
    "email": "[email protected]",
    "name": "John Doe"
  }
}
Save the token - you’ll need it for authenticated requests.
2

Search for a flight

Use the flight search endpoint to find available flights:
curl -X GET "http://localhost:3000/flight/search?iata=UA123&icao=UAL123&timezone=America/New_York" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
This returns a list of matching flights with their faFlightId (FlightAware ID) for detailed tracking.
3

Get detailed flight information

Retrieve comprehensive flight details including real-time position:
curl -X GET "http://localhost:3000/flight?iata=UA123&icao=UAL123&timezone=America/New_York&faFlightId=UAL123-1234567890" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
Response includes:
  • Real-time position data (latitude, longitude, altitude, speed)
  • Origin and destination information
  • Aircraft details and registration
  • Departure and arrival times (scheduled, estimated, actual)
  • Gate and terminal information
  • Flight status and progress percentage
4

Get the flight path

Retrieve all position data points for map visualization:
curl -X GET "http://localhost:3000/flight/track?iata=UA123&icao=UAL123&timezone=America/New_York" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
This returns an array of position coordinates with timestamps for drawing the flight path on a map.

​
Create a flight booking

Once you’ve tracked a flight, you can create a booking to save your travel details: 
curl -X POST http://localhost:3000/flight/booking \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "flightId": "clx1234567890",
    "bookingCode": "ABC123",
    "seatNumber": "12A",
    "seatType": "window",
    "seatingClass": "economy",
    "reason": "personal",
    "notes": "Traveling for vacation"
  }'
The flightId is returned when you track a flight. Bookings are linked to your user account for easy retrieval.

​
Search flights between airports

To find all flights between two airports on a specific date: 
curl -X GET "http://localhost:3000/flights?from=LAX&to=JFK&date=2024-03-20" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
This returns all available flights with:
  • Flight numbers (IATA and ICAO)
  • Airline information
  • Departure and arrival times
  • Aircraft type

​
Using the Flutter mobile app

1

Navigate to the app directory

cd app
flutter pub get
2

Configure API endpoint

Set your API URL in the environment:
# For debug builds
flutter run --dart-define=API_URL_DEBUG=http://localhost:3000

# For production builds
flutter run --dart-define=API_URL_PRODUCTION=https://api.yourdomain.com
3

Add Mapbox API key

The app uses Mapbox for map visualization:
flutter run --dart-define=MAPBOX_API_KEY=your-mapbox-key
4

Run the app

flutter run
The app includes:
  • Flight search interface
  • Interactive map with flight paths
  • Home screen widgets for quick access
  • Booking management
  • User profile and statistics

​
API code examples

Here are examples using the auto-generated Dart client (from OpenAPI spec): 
import 'package:openapi/openapi.dart';
import 'package:dio/dio.dart';

// Initialize the client
final openapi = Openapi(
  dio: Dio(
    BaseOptions(
      baseUrl: 'http://localhost:3000',
    ),
  ),
);

// Register a user
final authResponse = await openapi.getAuthApi().authControllerRegister(
  registerDTO: RegisterDTO(
    email: '[email protected]',
    password: 'securepassword',
    name: 'John Doe',
  ),
);

final token = authResponse.data?.token;

// Search for flights
final searchResponse = await openapi.getFlightApi().flightControllerSearchFlights(
  iata: 'UA123',
  icao: 'UAL123',
  timezone: 'America/New_York',
);

// Get flight details
final flightResponse = await openapi.getFlightApi().flightControllerGetFlight(
  iata: 'UA123',
  icao: 'UAL123',
  timezone: 'America/New_York',
  faFlightId: 'UAL123-1234567890',
);

​
Next steps

Architecture overview

Learn about the monorepo structure and system design

API reference

Explore the complete API documentation

Mobile app guide

Deep dive into Flutter app development

Wear OS integration

Build the Wear OS companion app

Build docs developers (and LLMs) love

Get started for freeTalk to us