API Gateway

The central entry point for the Melodia music streaming platform, providing unified API routing, authentication, and request management across all microservices.

Table of Contents

• Overview
• Getting Started
• Development Workflow
• Project Structure

Overview

The API Gateway is a Node.js-based service that acts as the single entry point for all client requests in the Melodia platform. Built with TypeScript and Express, it provides:

• Unified API Routing: Centralized routing to all microservices (Users, Artists, Libraries, Metrics, Notifications)
• Authentication & Authorization: JWT-based authentication with role-based access control
• Request Proxying: Intelligent request forwarding to backend services
• Deep Link Handling: Mobile app deep link management
• API Documentation: Comprehensive OpenAPI/Swagger documentation
• Request Logging: Centralized logging for monitoring and debugging

Key Features

• Token-based authentication with JWT
• Admin and artist role management
• Service health monitoring
• CORS configuration
• Swagger UI for API exploration
• Hot-reload development environment
• Integration with all Melodia microservices

Getting Started

Prerequisites

Before you begin, ensure you have the following installed on your system:

• Node.js (v20 or higher) - Download
• npm (comes with Node.js) or yarn
• Docker and Docker Compose - Download

1. Clone the Repository

git clone https://github.com/MelodiApp/gateway.git
cd gateway

2. Install Dependencies

npm install

3. Environment Setup

Copy the example environment file and configure your environment variables:

cp .env.example .env

Edit the .env file with your configuration. The default values are configured for local development with Docker Compose.

Key environment variables:

• PORT: Gateway port (default: 8091)
• PUBLIC_KEY_PATH: Path to JWT public key for token verification
• USERS_URL, ARTISTS_URL, etc.: URLs of backend microservices
• DISABLE_AUTH: Set to true for development without authentication

4. Create Docker Network

The gateway requires a shared Docker network to communicate with other microservices:

docker network create melodiapp-net

Note: This network is shared across all Melodia microservices. You only need to create it once, even if you're running multiple services.

5. Start Development Environment

Start the gateway using Docker Compose:

# Start the gateway
docker compose up --build -d

The gateway will be available at http://localhost:8091

6. Verify Installation

Once the service is running, you can verify the installation:

# Check if the API is responding
curl http://localhost:8091/health

# View API documentation
open http://localhost:8091/api-docs

Development Workflow

Running the Application

The service is configured with hot-reload enabled. Any code changes will automatically restart the server:

# Start the development environment
docker compose up --build -d

# View logs in real-time
docker compose logs -f gateway

# Stop the services
docker compose down

Working with Microservices

The gateway proxies requests to backend microservices. For local development, ensure the required microservices are running:

• Users Service (port 8092) - Required for authentication
• Artists Service (port 8093) - For artist-related endpoints
• Libraries Service (port 8094) - For playlists and saved content
• Metrics Service (port 8095) - For analytics and play counts
• Notifications Service (port 8096) - For push notifications

Code Quality

# Run linter
npx eslint .

# Fix linting issues automatically
npx eslint . --fix

# Format code with Prettier
npx prettier --write .

# Check code formatting
npx prettier --check .

Project Structure

.
├── .env.example           # Environment variables template
├── .gitignore             # Git ignore rules
├── .prettierignore        # Prettier ignore rules
├── docker compose.yml     # Docker services configuration
├── Dockerfile             # Docker image build instructions
├── eslint.config.mjs      # ESLint configuration
├── package.json           # Dependencies and scripts
├── Procfile               # Heroku deployment configuration
├── README.md              # This file
├── tsconfig.json          # TypeScript compiler configuration
│
├── api/
│   └── bruno/             # API testing collections (Bruno)
│
├── logs/                  # Application logs
│
└── src/
    ├── index.ts           # Application entry point
    ├── app.ts             # Express server configuration
    │
    ├── controllers/       # HTTP request handlers
    │   ├── admin.controller.ts
    │   ├── artist.controller.ts
    │   ├── base.controller.ts
    │   ├── libraries.controller.ts
    │   ├── metrics.controller.ts
    │   ├── notifications.controller.ts
    │   ├── search.controller.ts
    │   └── user.controller.ts
    │
    ├── routes/            # API endpoint definitions
    │   ├── admin.route.ts
    │   ├── artist.route.ts
    │   ├── libraries.route.ts
    │   ├── metrics.route.ts
    │   ├── notifications.route.ts
    │   ├── search.route.ts
    │   └── user.route.ts
    │
    ├── services/          # Business logic
    │   ├── deep-link.service.ts
    │   ├── proxy.service.ts
    │   └── search.service.ts
    │
    ├── docs/
    │   └── swagger.yaml   # OpenAPI/Swagger specification
    │
    ├── utils/             # Utilities and helpers
    │   ├── async.handler.ts
    │   ├── config.ts
    │   ├── logger.ts
    │   ├── swagger.ts
    │   ├── keys/          # JWT public/private keys
    │   ├── middlewares/
    │   │   ├── admin.middleware.ts
    │   │   ├── auth.middleware.ts
    │   │   ├── error.middleware.ts
    │   │   └── request-logger.middleware.ts
    │   └── templates/
    │       ├── html.templates.ts
    │       └── template.ts
    │
    └── views/             # HTML templates
        ├── no-app.html
        └── open-app.html

License

This project is part of the Melodia platform.

Team

MelodiApp Development Team

Name	Last Name	Email
Ian	von der Heyde	ivon@fi.uba.ar
Valentín	Schneider	vschneider@fi.uba.ar
Daniela	Ojeda	dojeda@fi.uba.ar
Alan	Cantero	acantero@fi.uba.ar
Ezequiel	Lazarte	ezlazarte@fi.uba.ar

Related Services

• Mobile Frontend - Melodia mobile application
• Web Frontend - Melodia backoffice application
• Artists Service - Manages artists, songs, albums, and discography
• Libraries Service - Manages user playlists and saved content
• Metrics Service - Handles play counts and analytics
• Notifications Service - Sends notifications for new releases
• Users Service - Manages user authentication and profiles
• LocalStack - Local AWS cloud stack for development