Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/luiss811/Backend-Airguide/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through cloning the AirGuide Backend, wiring up your environment variables, seeding the database, and completing a full authentication flow — from registering a new account to receiving a JWT token via two-factor verification.
1

Clone the repo and install dependencies

Clone the repository and install all dependencies. The --legacy-peer-deps flag is required to resolve peer dependency conflicts in the current package set.
git clone https://github.com/luiss811/Backend-Airguide.git
cd Backend-Airguide
npm install --legacy-peer-deps
2

Set up environment variables

Create a .env file in the project root with the following values. Replace placeholder credentials with your own before deploying to production.
DATABASE_URL="postgres://<user>:<password>@pooled.db.prisma.io:5432/postgres?sslmode=require"

# API base URL (development)
API_URL="http://localhost:3001/api"

# Google Maps/Routes API key
API_KEY="your-google-api-key"
GOOGLE_ROUTES_API_KEY="your-google-api-key"

# Server
NODE_ENV="development"

# JWT
JWT_SECRET="your-jwt-secret"
JWT_EXPIRES_IN="1d"

# CORS allowed origin
CORS_ORIGIN="http://localhost:5173"

# Email / SMTP (used for 2FA OTP delivery)
# For Gmail, generate an App Password at https://myaccount.google.com/apppasswords
SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_SECURE="false"
SMTP_USER="your-email@gmail.com"
SMTP_PASS="your-app-password"
SMTP_FROM="AirGuide <your-email@gmail.com>"
The SMTP_* variables are required. The auth service sends a one-time password to the user’s email address during every login attempt.
3

Run database migrations

Generate the Prisma client, apply migrations to your database, and seed it with initial data.
npm run prisma:generate
npm run prisma:migrate
npm run prisma:seed
  • prisma:generate — builds the type-safe Prisma client from your schema.
  • prisma:migrate — applies all pending SQL migrations to the target database.
  • prisma:seed — populates the database with buildings, rooms, and other reference data.
4

Start all services

The dev script uses concurrently to launch the API Gateway and all five microservices with hot reload.
npm run dev
Once running, the gateway is available at http://localhost:3001. You can confirm it is healthy with:
curl http://localhost:3001/health

{
  "status": "ok",
  "timestamp": "2026-05-21T00:00:00.000Z",
  "service": "API Gateway"
}
5

Make your first API call

The authentication flow has three steps: register, log in to receive an OTP, then verify the OTP to obtain a JWT token.1. Register a new account
curl -X POST http://localhost:3001/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "correo": "ana.garcia@universidad.edu",
    "password": "S3cur3P@ssword",
    "nombre": "Ana García",
    "matricula": "A12345678"
  }'

{
  "message": "Registro exitoso. Tu cuenta está pendiente de validación por un administrador.",
  "usuario": {
    "id": 42,
    "correo": "ana.garcia@universidad.edu",
    "nombre": "Ana García",
    "matricula": "A12345678",
    "rol": "alumno",
    "estado": "pendiente"
  }
}
New accounts are created with estado: "pendiente". You cannot log in until an administrator approves the account by setting its state to "activo" via PUT /api/auth/validate/:id.
2. Log in to receive a one-time passwordOnce your account is active, send your credentials to receive an OTP by email.
curl -X POST http://localhost:3001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "correo": "ana.garcia@universidad.edu",
    "password": "S3cur3P@ssword"
  }'

{
  "requiresTwoFactor": true,
  "correo": "ana.garcia@universidad.edu",
  "message": "Código de verificación enviado a tu correo electrónico."
}
3. Verify the OTP to obtain a JWT tokenSubmit the six-digit code delivered to your email inbox.
curl -X POST http://localhost:3001/api/auth/verify-2fa \
  -H "Content-Type: application/json" \
  -d '{
    "correo": "ana.garcia@universidad.edu",
    "codigo": "483921"
  }'

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "usuario": {
    "id": 42,
    "correo": "ana.garcia@universidad.edu",
    "nombre": "Ana García",
    "matricula": "A12345678",
    "rol": "alumno",
    "prioridad": 4,
    "estado": "activo"
  }
}
Pass the returned token as a Bearer token in the Authorization header for all subsequent requests.
curl http://localhost:3001/api/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Build docs developers (and LLMs) love

Get started for freeTalk to us