Aviation Integration Service

RESTful API developed in Node.js + TypeScript for integration with AviationStack and for querying flight and airline information.
Includes a complete environment with Docker Compose, automated tests, and fallback in case of external failures.

---

Badges

Build and test automation via GitHub Actions

---

Included Services (Docker Compose)

• Node.js (Express, TypeScript)
• MySQL 8
• Redis
• phpMyAdmin
• Mailhog (email testing)

---

Quick Start

1. Make sure you have Docker and Docker Compose installed.
2. Copy the .env.example file to .env and adjust variables if necessary.
3. To build the images and create the volumes, run

make init

4. To start all services use:

make start

5. To stop them use:

make stop-dev

---

🌐 Production Demo

You can try the API deployed on Cloud Run here:

👉 https://aviation-integration-944235041157.us-central1.run.app/

• Healthcheck: /api/health
• Swagger UI: /docs
• Flights example: /api/v1/flights?dep_iata=GUA
• Airports example: /api/v1/airports?search=guatemala
• Airlines example: /api/v1/airlines?search=VX

---

Quick Commands

make init # Initialize network, volumes, and services
make start # Start all development services
make stop-dev # Stop all development services
make node-shell # Enter Node.js terminal
make db-shell # Enter MySQL terminal
make redis-shell # Enter Redis terminal
make mailhog # Open Mailhog in the browser
make phpmyadmin # Open phpMyAdmin in the browser
make test # Run tests inside the Node.js container

---

Environment Variables

See .env.example for the necessary configuration.
Glossary:

Variable	Description
NODE_ENV	Environment (development, production, etc)
PORT	API port (default: 8080)
AVIATIONSTACK_KEY	AviationStack API Key
AVIATIONSTACK_URL	AviationStack API URL
MYSQL_*	MySQL configuration
REDIS_*	Redis configuration
MAIL** / GMAIL**	SMTP/Mailhog/Gmail for testing

---

API Documentation

• Swagger UI: https://aviation-integration-944235041157.us-central1.run.app/docs
• docs/API.md — English version with endpoints summary, parameters and examples
• Main endpoints:

Method	Path	Description
GET	/api/v1/airlines	List of airlines with local search
GET	/api/v1/airports	List of airports with local search
GET	/api/v1/flights	Flight search with multiple filters
GET	/api/health	Check the status of all services

---

Parameter Validation

All query parameters are validated with Joi, and validation errors return HTTP 422.
See src/utils/airportValidator.ts, src/utils/flightsValidator.ts y src/utils/airlineValidator.ts.

---

Fallback and Caching

• If the external API fails, the system first checks Redis, then MySQL.
• All successful external responses are automatically persisted.
• A TTL is applied to Redis cache.

---

Automated Testing

Full support for:

• ✔️ Unit tests for controllers, services, validators, and middleware
• ✔️ Integration tests for REST endpoints
• ✔️ Data mocking for NODE_ENV=test to avoid real calls to AviationStack

To run:

make init
make test

---

Architecture and Diagrams

• Data flow diagram:
  docs/data-flow.puml
• Architecture diagram:
  docs/architecture.puml

---

Quick Troubleshooting

• MySQL won't start? Delete the Docker volume:

  docker volume rm aviation_db_data

• API not responding on port? Check your .env and exposed ports.

---

CI/CD and Deploy

• Automatic deploy:
  When merging develop → master, it deploys to Cloud Run via GitHub Actions and the GCP_SA_KEY secret.
• Manual deploy: If you need to deploy manually:
  1. Obtain a service account key in JSON format with Cloud Run Admin, Storage Admin, and Cloud Build permissions.
  2. Authenticate with:

     gcloud auth activate-service-account --key-file gcp-key.json

  3. Launch the deploy:

     make deploy

---

Linter and Dependencies

• Run before every PR

npm run lint
npm run format

• Audit dependencies regularly with

npm audit

---

Contributing

Please review the CONTRIBUTING.md before submitting a pull request.

---

License

MIT
Author: @jdanielrodriguez