docs/API_GATEWAY.md

# API Gateway for RAG Agent Framework

A production-ready, multi-protocol API Gateway for the AmaniQuery RAG Agent Framework. Provides unified access for frontend clients with comprehensive security, observability, and performance features.

## Architecture

![API Gateway Architecture](docs/images/api-gateway-architecture.png)

```mermaid
graph TB
    subgraph "Client Layer"
        WEB[Web Browser]
        MOBILE[Mobile App]
        DEVELOPER[Developer Portal]
    end
    
    subgraph "API Gateway Layer"
        GW[API Gateway<br/>Go Service]
        
        subgraph "Middleware Stack"
            CORS[CORS Handler]
            RATE[Rate Limiter]
            AUTH[JWT Validator]
            AUDIT[Audit Logger]
        end
        
        subgraph "Protocol Handlers"
            REST[REST Handler]
            WS[WebSocket Handler]
            GQL[GraphQL Handler]
        end
    end
    
    subgraph "Backend Services"
        AGENT[Agent Service]
        RETRIEVER[Retriever Service]
        GENERATOR[Generator Service]
        MEMORY[Memory Service]
    end
    
    WEB --> GW
    MOBILE --> GW
    DEVELOPER --> GW
    
    GW --> CORS --> RATE --> AUTH --> AUDIT
    AUDIT --> REST
    AUDIT --> WS
    AUDIT --> GQL
    
    REST --> AGENT
    WS --> AGENT
    GQL --> AGENT
```

## Features

### Multi-Protocol Support
- **REST API** - Standard HTTP endpoints for queries, agents, memory
- **WebSocket** - Real-time streaming for query responses
- **Server-Sent Events** - Lightweight streaming alternative
- **GraphQL** - Flexible query interface (placeholder)

### Security
- **JWT Authentication** - Token-based auth with HMAC/RSA signing
- **OPA Authorization** - Fine-grained policy-based access control
- **Rate Limiting** - Token bucket with per-tenant/user isolation
- **CORS** - Configurable cross-origin policies
- **Security Headers** - HSTS, CSP, X-Frame-Options, etc.

### Observability
- **Prometheus Metrics** - Request counts, latencies, cache hits
- **OpenTelemetry Tracing** - Distributed request tracing
- **Audit Logging** - Structured logs for compliance

### Performance
- **Redis Caching** - Query response caching with smart TTL
- **Circuit Breakers** - Failure isolation per service
- **Connection Pooling** - Efficient gRPC connections

## Quick Start

### Prerequisites
- Go 1.21+
- Docker & Docker Compose
- Redis (for caching/rate limiting)

### Running Locally

```bash
# Clone the repository
cd AmaniQuery

# Copy example config
cp gateway.example.yaml gateway.yaml

# Run with Docker Compose
cd deployments/docker
docker-compose up -d api-gateway
```

### Configuration

See `gateway.example.yaml` for all options. Key settings:

```yaml
server:
  bindAddr: ":8443"
  
auth:
  jwtSecret: "${JWT_SECRET}"
  
cache:
  redisAddr: "redis:6379"
```

Environment variables override config with `GATEWAY_` prefix.

## API Endpoints

### Queries
| Method | Path | Description |
|--------|------|-------------|
| POST | `/v2/queries` | Execute RAG query |
| GET | `/v2/queries/{id}` | Get async query result |
| WS | `/v2/queries/stream` | Streaming query |

### Agents
| Method | Path | Description |
|--------|------|-------------|
| POST | `/v2/agents` | Create agent |
| GET | `/v2/agents/{id}` | Get agent |
| DELETE | `/v2/agents/{id}` | Delete agent |
| POST | `/v2/agents/{id}/execute` | Execute plan |

### Memory
| Method | Path | Description |
|--------|------|-------------|
| GET | `/v2/memory/context` | Get context window |
| POST | `/v2/memory/sessions/{id}/consolidate` | Consolidate memory |

### Admin
| Method | Path | Description |
|--------|------|-------------|
| GET | `/admin/health` | Health check |
| GET | `/admin/metrics` | Prometheus metrics |

## WebSocket Protocol

```javascript
// Connect
const ws = new WebSocket('wss://api.example.com/v2/queries/stream?token=JWT');

// Send query
ws.send(JSON.stringify({
  type: 'query',
  payload: { query: 'What is RAG?', userId: 'user-123' }
}));

// Receive chunks
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.type === 'chunk') console.log(msg.data);
  if (msg.type === 'done') console.log('Complete');
};
```

## Deployment

### Docker
```bash
docker build -f deployments/docker/Dockerfile.gateway -t api-gateway .
docker run -p 8443:8443 api-gateway
```

### Kubernetes
```bash
kubectl apply -f deployments/k8s/gateway.yaml
```

## Project Structure

```
internal/gateway/
├── config.go           # Configuration
├── gateway.go          # Main server
├── types.go            # Request/response types
├── cache/
│   └── cache.go        # Redis cache
├── handlers/
│   ├── query.go        # Query endpoints
│   ├── websocket.go    # WebSocket streaming
│   ├── agent.go        # Agent CRUD
│   ├── memory.go       # Memory endpoints
│   ├── admin.go        # Health/metrics
│   └── auth.go         # Token endpoint
├── middleware/
│   ├── cors.go         # CORS handling
│   ├── ratelimit.go    # Rate limiting
│   ├── auth.go         # JWT + OPA auth
│   ├── audit.go        # Audit logging
│   └── tracing.go      # OpenTelemetry
├── observability/
│   └── metrics.go      # Prometheus metrics
└── services/
    ├── registry.go     # Service discovery
    └── clients.go      # gRPC clients
```

## License

Apache 2.0