# Yemaya API Gateway

Traefik-based API gateway for the Yemaya creative production platform.

## Overview

The API gateway provides:

- **Request Routing**: Route requests to appropriate backend services
- **Load Balancing**: Distribute traffic across service instances
- **TLS Termination**: Handle HTTPS with automatic Let's Encrypt certificates
- **Rate Limiting**: Protect services from abuse
- **Authentication**: JWT and API key validation via forward auth
- **CORS**: Cross-origin resource sharing configuration
- **Security Headers**: HSTS, CSP, XSS protection, etc.
- **Health Checks**: Service health monitoring
- **Metrics**: Prometheus metrics for monitoring
- **Tracing**: Distributed tracing with Jaeger

## Architecture

```
                    ┌─────────────────────────────────────────┐
                    │           Traefik API Gateway           │
                    │                                         │
   Internet ───────►│  :80 (HTTP) ──► Redirect to HTTPS      │
                    │  :443 (HTTPS) ──► Route to services    │
                    │  :50051 (gRPC) ──► gRPC services       │
                    │  :8082 (Metrics) ──► Prometheus        │
                    └───────────────────┬─────────────────────┘
                                        │
           ┌────────────────────────────┼────────────────────────────┐
           │                            │                            │
           ▼                            ▼                            ▼
    ┌─────────────┐             ┌─────────────┐             ┌─────────────┐
    │ API Service │             │Auth Service │             │ WS Service  │
    │   :3000     │             │   :3001     │             │   :3002     │
    └─────────────┘             └─────────────┘             └─────────────┘
```

## Quick Start

### Development

```bash
# Start the gateway in development mode
docker compose -f docker-compose.dev.yml up -d

# View logs
docker compose -f docker-compose.dev.yml logs -f traefik

# Access dashboard
open http://localhost:8080
```

### Production

```bash
# Copy environment file
cp .env.example .env

# Edit configuration
vi .env

# Generate dashboard password hash
htpasswd -nb admin yourpassword | sed -e s/\\$/\\$\\$/g

# Start the gateway
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
```

## Configuration

### Directory Structure

```
gateway/
├── config/
│   ├── traefik.yml           # Static configuration
│   └── dynamic/
│       ├── services.yml      # Service routing
│       ├── middleware.yml    # Middleware definitions
│       ├── middleware-dev.yml # Development overrides
│       ├── tls.yml           # TLS configuration
│       └── health.yml        # Health check endpoints
├── certs/                    # TLS certificates
├── scripts/
│   └── generate-dev-certs.sh # Generate dev certificates
├── docker-compose.yml        # Base compose file
├── docker-compose.dev.yml    # Development override
├── docker-compose.prod.yml   # Production override
└── .env.example              # Environment template
```

### Environment Variables

| Variable                          | Description             | Default     |
| --------------------------------- | ----------------------- | ----------- |
| `DOMAIN`                          | Base domain for routing | `localhost` |
| `ACME_EMAIL`                      | Let's Encrypt email     | -           |
| `TRAEFIK_DASHBOARD_USER`          | Dashboard username      | `admin`     |
| `TRAEFIK_DASHBOARD_PASSWORD_HASH` | Bcrypt password hash    | -           |
| `LOG_LEVEL`                       | Logging level           | `INFO`      |

## Routing

### API Routes

| Route                    | Service      | Description            |
| ------------------------ | ------------ | ---------------------- |
| `api.{domain}/v1/*`      | api-service  | Main REST API          |
| `api.{domain}/docs`      | api-service  | Swagger UI             |
| `api.{domain}/reference` | api-service  | Scalar API Reference   |
| `api.{domain}/health`    | api-service  | Health endpoints       |
| `auth.{domain}/*`        | auth-service | Authentication service |
| `ws.{domain}`            | ws-service   | WebSocket connections  |
| `cdn.{domain}/*`         | cdn-service  | Asset delivery         |

### gRPC Routes

gRPC services are available on port `50051`:

- Auth Service
- User Service
- Project Service
- Asset Service

## Middleware

### Rate Limiting

| Middleware                  | Limit       | Use Case       |
| --------------------------- | ----------- | -------------- |
| `rate-limit`                | 100 req/min | Standard API   |
| `rate-limit-auth`           | 60 req/min  | Auth endpoints |
| `rate-limit-password-reset` | 5 req/hour  | Password reset |
| `rate-limit-upload`         | 30 req/min  | File uploads   |

### Security Headers

All responses include:

- `Strict-Transport-Security` (HSTS)
- `Content-Security-Policy` (CSP)
- `X-Content-Type-Options: nosniff`
- `X-Frame-Options: DENY`
- `X-XSS-Protection: 1; mode=block`
- `Referrer-Policy: strict-origin-when-cross-origin`

### Authentication

Forward authentication to the auth service:

- `jwt-auth`: Validates JWT tokens
- `api-key-auth`: Validates API keys
- `optional-auth`: Non-blocking auth check

## Health Checks

| Endpoint           | Description           |
| ------------------ | --------------------- |
| `/gateway/health`  | Gateway health status |
| `/gateway/metrics` | Prometheus metrics    |

## Monitoring

### Prometheus Metrics

Metrics are exposed on port `8082`:

```
http://localhost:8082/metrics
```

Available metrics:

- `traefik_entrypoint_requests_total`
- `traefik_entrypoint_request_duration_seconds`
- `traefik_service_requests_total`
- `traefik_service_request_duration_seconds`

### Grafana Dashboard

Import the Traefik dashboard from Grafana:

- Dashboard ID: 17346

## TLS Configuration

### Development

Generate self-signed certificates:

```bash
./scripts/generate-dev-certs.sh localhost
```

### Production

Let's Encrypt certificates are automatically obtained and renewed.

TLS options:

- Minimum version: TLS 1.2
- Preferred: TLS 1.3
- Strong cipher suites only

## Troubleshooting

### View Logs

```bash
# All logs
docker compose logs -f traefik

# Access logs only
docker compose logs -f traefik 2>&1 | grep accesslog
```

### Debug Mode

Enable debug logging:

```bash
docker compose -f docker-compose.dev.yml up -d
```

### Test Routes

```bash
# Test whoami service
curl http://localhost/whoami

# Test with host header
curl -H "Host: api.localhost" http://localhost/health
```

### Check Configuration

```bash
# Validate configuration
docker compose exec traefik traefik healthcheck

# View current configuration
curl http://localhost:8080/api/rawdata/routers
```

## Security Considerations

1. **Never expose the dashboard in production** without authentication
2. **Use strong passwords** for dashboard access
3. **Review rate limits** based on your traffic patterns
4. **Monitor for suspicious activity** using access logs
5. **Keep Traefik updated** for security patches
6. **Use network policies** to restrict internal traffic

## Contributing

When modifying the gateway configuration:

1. Test changes in development first
2. Validate configuration syntax
3. Check for breaking changes in routing
4. Update this documentation
5. Test with all backend services
