# ADR-0032: API Gateway Strategy

## Status
Accepted

## Context
The platform follows a microservices architecture where each service is independently deployable. We need a central entry point that handles:

- Request routing to backend services
- Authentication and authorization at the edge
- Rate limiting and throttling
- CORS and request/response transformation
- Service discovery integration

Options considered:
1. **Custom API Gateway** - Build our own gateway service
2. **Kong** - Open-source API Gateway
3. **Envoy** - High-performance proxy
4. **Traefik** - Modern reverse proxy

## Decision
Implement a **custom API Gateway service** as a core infrastructure component in Epic 1:

1. **API Gateway as Core Component**:
   - Entry point: `cmd/api-gateway/`
   - Implementation: `services/gateway/internal/`
   - Implemented in Epic 1 (not deferred to Epic 8)
   - Required for microservices architecture, not optional

2. **Responsibilities**:
   - **Request Routing**: Route requests to backend services via service discovery
   - **Authentication**: Validate JWT tokens via Auth Service
   - **Authorization**: Check permissions via Authz Service (for route-level auth)
   - **Rate Limiting**: Per-user and per-IP rate limiting
   - **CORS**: Handle cross-origin requests
   - **Request Transformation**: Modify requests before forwarding
   - **Response Transformation**: Modify responses before returning
   - **Load Balancing**: Distribute requests across service instances

3. **Integration Points**:
   - Service registry for service discovery
   - Auth Service client for token validation
   - Authz Service client for permission checks
   - Cache (Redis) for rate limiting state

4. **Implementation Approach**:
   - Built with Go (Gin/Echo framework)
   - Uses service clients for backend communication
   - Configurable routing rules
   - Middleware-based architecture

## Architecture

```mermaid
graph TB
    Client[Client] --> Gateway[API Gateway<br/>:8080]
    
    Gateway --> AuthClient[Auth Service Client]
    Gateway --> AuthzClient[Authz Service Client]
    Gateway --> ServiceRegistry[Service Registry]
    Gateway --> Cache[Cache<br/>Rate Limiting]
    
    AuthClient --> AuthSvc[Auth Service<br/>:8081]
    AuthzClient --> AuthzSvc[Authz Service<br/>:8083]
    ServiceRegistry --> BackendSvc[Backend Services]
    
    Gateway --> BackendSvc
    
    style Gateway fill:#4a90e2,stroke:#2e5c8a,stroke-width:3px,color:#fff
    style AuthSvc fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px,color:#fff
    style BackendSvc fill:#7b68ee,stroke:#5a4fcf,stroke-width:2px,color:#fff
```

## Request Flow

```mermaid
sequenceDiagram
    participant Client
    participant Gateway
    participant AuthSvc
    participant AuthzSvc
    participant Registry
    participant BackendSvc
    
    Client->>Gateway: HTTP Request
    Gateway->>Gateway: Rate limiting check
    Gateway->>AuthSvc: Validate JWT (gRPC)
    AuthSvc-->>Gateway: Token valid + user info
    Gateway->>AuthzSvc: Check route permission (gRPC, optional)
    AuthzSvc-->>Gateway: Authorized
    Gateway->>Registry: Discover backend service
    Registry-->>Gateway: Service endpoint
    Gateway->>BackendSvc: Forward request (gRPC/HTTP)
    BackendSvc-->>Gateway: Response
    Gateway-->>Client: HTTP Response
```

## Consequences

### Positive
- **Single Entry Point**: All external traffic goes through one gateway
- **Centralized Security**: Authentication and authorization at the edge
- **Performance**: Rate limiting and caching at gateway level
- **Flexibility**: Easy to add new routes and services
- **Consistency**: Uniform API interface for clients
- **Observability**: Central point for metrics and logging

### Negative
- **Single Point of Failure**: Gateway failure affects all traffic
- **Additional Latency**: Extra hop in request path
- **Complexity**: Additional service to maintain and deploy
- **Scaling**: Gateway must scale to handle all traffic

### Mitigations
1. **High Availability**: Deploy multiple gateway instances behind load balancer
2. **Circuit Breakers**: Implement circuit breakers for backend service failures
3. **Caching**: Cache authentication results and service endpoints
4. **Monitoring**: Comprehensive monitoring and alerting
5. **Graceful Degradation**: Fallback mechanisms for service failures

## Implementation Strategy

### Epic 1: Core Infrastructure
- Create `cmd/api-gateway/` entry point
- Implement basic routing with service discovery
- JWT validation via Auth Service client
- Rate limiting middleware
- CORS support

### Epic 2-3: Enhanced Features
- Permission-based routing (via Authz Service)
- Request/response transformation
- Advanced load balancing
- Health check integration

## Configuration

```yaml
gateway:
  port: 8080
  routes:
    - path: /api/v1/auth/**
      service: auth-service
      auth_required: false
    - path: /api/v1/users/**
      service: identity-service
      auth_required: true
      permission: user.read
    - path: /api/v1/blog/**
      service: blog-service
      auth_required: true
      permission: blog.post.read
  rate_limiting:
    enabled: true
    per_user: 100/minute
    per_ip: 1000/minute
  cors:
    allowed_origins: ["*"]
    allowed_methods: ["GET", "POST", "PUT", "DELETE"]
```

## References
- [ADR-0029: Microservices Architecture](./0029-microservices-architecture.md)
- [ADR-0030: Service Communication Strategy](./0030-service-communication-strategy.md)
- [ADR-0031: Service Repository Structure](./0031-service-repository-structure.md)
- [API Gateway Pattern](https://microservices.io/patterns/apigateway.html)