Backend API‐Gateway Guide

Backend Developer Guide — API Gateway

Overview

The API Gateway is the single entry point for all external traffic. The frontend never calls backend services directly — everything goes through the gateway first.

Port: 3001
Swagger UI: http://localhost:3001/api-docs

---

Architecture

Frontend → API Gateway (port 3001) → Accounts Service (port 3002) → Mailing Service (port 3003) ← coming soon

---

How It Works

1. Frontend sends a request to the gateway
2. For protected routes, the gateway validates the JWT using Auth0's public keys
3. The gateway forwards the request to the correct downstream service
4. The downstream response is passed back to the frontend

---

Current Endpoints

Method	Path	Auth Required
POST	/api/accounts/auth/register	No
POST	/api/accounts/auth/login	No
GET	/api/accounts/auth/me	Yes

---

Adding a New Service

1. Add the service URL to .env:

MAILING_SERVICE_URL=http://mailing_app:3003

2. Create a controller under src/your-service/ following the same pattern as src/accounts/accounts.controller.ts

3. Use ProxyService to forward requests:

return this.proxy.forward({
  url: `${this.serviceUrl}/api/endpoint`,
  method: 'POST',
  data: body,
});

4. Register the module in app.module.ts

---

Protecting Routes

Add @UseGuards(JwtAuthGuard) to any route requiring authentication. After validation req.user contains:

{ auth0Id: string, email: string, role: 'user' | 'analyst' | 'admin' }

---

Running the Gateway

# Local dev
pnpm build:api-gateway
cd project/backend/api-gateway && pnpm start:prod

# Docker
pnpm dc:up:backend