Skip to main content

API Gateway

Ultra-thin routing layer for Helix platform with <10ms latency overhead.

Overview​

The API Gateway is the single public entry point for all client requests. It provides:

  • Stream-based request proxying to backend services
  • CORS configuration
  • Security headers (Helmet)
  • Response compression
  • Async rate limiting (non-blocking)
  • Unified health checks

What it does NOT do:

  • Full JWT validation (services handle this)
  • Authentication middleware (services handle this)
  • Tenant context initialization (services handle this)
  • Database access (no DatabaseService)

Performance​

Latency overhead: <10ms

  • Stream-based proxy: 2-5ms
  • CORS headers: <1ms
  • Request ID: <1ms
  • Rate limiting: 0ms (async, fire-and-forget)

Endpoints​

Gateway Health​

  • GET /health - Gateway health status
  • GET /heartbeat - Lightweight liveness check
  • GET /info - Service metadata

Proxied Service Health​

  • GET /health/auth → auth-service:3001/health
  • GET /health/tenant → tenant-service:3002/health
  • GET /health/admin → admin-service:3003/health
  • GET /health/file → file-service:3004/health
  • GET /health/kira → kira-service:3010/health
  • GET /health/vera → vera-service:3011/health
  • GET /health/cleverscreen → cleverscreen-service:3012/health

API Routes (Proxied)​

  • POST /api/auth/* → auth-service:3001
  • GET /api/tenants/* → tenant-service:3002
  • GET /api/users/* → admin-service:3003
  • POST /api/files/* → file-service:3004
  • POST /api/kira/* → kira-service:3010
  • POST /api/vera/* → vera-service:3011
  • POST /api/cleverscreen/* → cleverscreen-service:3012

Environment Variables​

See .env.example in the project root for configuration:

  • SERVICE_PORT - Gateway port (default: 3000)
  • CORS_ORIGIN - Allowed origins (default: *)
  • {SERVICE}_URL - Internal service URLs

Development​

# Install dependencies
npm install

# Run Gateway
npx nx serve api-gateway

# Test health
curl http://localhost:3000/health

# Test proxy
curl http://localhost:3000/api/auth/health

Security Model​

Defense in Depth:

  1. Network Layer - Only port 3000 exposed in production
  2. Gateway Layer - CORS, Helmet, rate limiting, compression
  3. Service Layer - Full JWT validation, RBAC, tenant isolation

Gateway is NOT the security boundary - services validate everything independently.

Architecture​

Client → Gateway :3000 (public)
    ↓
http-proxy-middleware (streaming)
    ↓
Backend Services :300X (internal network only)
    ↓
Full auth validation + business logic

Testing​

# Build
npx nx build api-gateway

# Performance test
npx autocannon -c 100 -d 10 http://localhost:3000/api/auth/health

# Expected: Gateway adds &lt;10ms latency

Implementation Details​

For complete architecture and security analysis, see the source code in apps/api-gateway/.