docs(api-gateway): Update the context.md to reflect new structure

Author: 3nd3r1

services/api-gateway/CONTEXT.md

@@ -1,66 +1,107 @@
-# Kubin Server - Context
+# API Gateway - Context
 
-## What is the Server?
+## What is the API Gateway?
 
-The Kubin Server is a web service that stores, manages, and serves Kubernetes cluster snapshots. It provides the backend infrastructure for the entire Kubin platform, handling snapshot storage, user authentication, and API access.
+The API Gateway is the single entry point for all external requests to the Kubin platform. It handles routing, authentication, rate limiting, and serves as the orchestration layer between the CLI, Web UI, and the underlying microservices.
 
 ## Core Responsibilities
 
-### 1. Snapshot Storage
-- Stores uploaded snapshots securely
-- Manages snapshot metadata and indexing
-- Handles snapshot compression and decompression
-- Provides snapshot retrieval and download
-
-### 2. API Management
-- Exposes REST API for snapshot operations
-- Handles upload, download, and management requests
-- Provides search and filtering capabilities
-- Manages API rate limiting and security
-
-### 3. User Management
-- Handles user authentication and authorization
-- Manages user accounts and permissions
-- Controls access to public and private snapshots
-- Provides API key management for CLI access
-
-### 4. Data Management
-- Organizes snapshots by user and organization
-- Implements snapshot versioning and history
-- Manages snapshot retention and cleanup
-- Provides backup and recovery capabilities
+### 1. Request Routing
+
+- Routes requests to appropriate backend services
+- Load balances traffic across service instances
+- Handles service discovery and health checking
+- Provides unified API versioning (`/api/v1`, `/internal/api/v1`)
+
+### 2. Security & Authentication
+
+- TLS termination and security headers
+- JWT-based authentication validation
+- API rate limiting (100 concurrent uploads, 1000 queries/min)
+- CORS handling for web UI integration
+
+### 3. Traffic Management
+
+- Request/response middleware stack
+- Error handling and recovery
+- Request logging and monitoring
+- Graceful shutdown coordination
+
+## Architecture Role
+
+The API Gateway serves as the orchestration layer in Kubin's microservices architecture:
+
+**Upstream Services:**
+
+- **Upload Orchestrator**: Handles snapshot upload coordination
+- **Metadata Service**: Manages PostgreSQL-backed snapshot metadata
+- **Storage Service**: Coordinates S3 file operations
+- **Query Service**: Orchestrates data retrieval from multiple services
+- **Analytics Service**: Provides ClickHouse-powered log analytics
+
+**Client Interfaces:**
+
+- **CLI Tool**: Direct API access for snapshot uploads
+- **Web UI**: Internal API endpoints for frontend functionality
+
+## API Structure
+
+### External API (`/api/v1`)
+
+- `POST /api/v1/snapshots` - Initiate snapshot upload (→ Upload Orchestrator)
+- `GET /api/v1/snapshots` - List snapshots (→ Metadata Service)
+
+### Internal API (`/internal/api/v1`)
+
+- `GET /internal/api/v1/snapshots/{id}/resources` - Get snapshot resources
+- `GET /internal/api/v1/snapshots/{id}/pods` - Get pod information
+- `GET /internal/api/v1/snapshots/{id}/logs` - Get pod logs (→ Analytics Service)
+- `GET /internal/api/v1/snapshots/{id}/namespaces` - Get namespaces
+
+## Communication Patterns
+
+### Synchronous Routing
+
+- CLI upload requests → Upload Orchestrator (immediate response)
+- Web UI queries → Query Service (real-time data)
+- File operations → Storage Service (direct S3 coordination)
+
+### Middleware Stack
+
+1. **Recovery**: Panic recovery and error handling
+2. **Logging**: Request/response logging
+3. **Security**: Headers, CORS, authentication
+4. **JSON**: Content-type management
+
+## Integration with Microservices Architecture
+
+The API Gateway is part of Kubin's distributed system that separates concerns:
+
+- **Upload Path**: API Gateway → Upload Orchestrator → Storage Service → Kafka → Log Processor
+- **Query Path**: API Gateway → Query Service → (Metadata Service + Analytics Service + Storage Service)
+- **Caching**: Redis integration for performance optimization
 
 ## Key Features
 
-- **RESTful API**: Standard HTTP/JSON API for all operations
-- **Authentication**: JWT-based user authentication
-- **Authorization**: Role-based access control
-- **Search**: Full-text search across snapshots
-- **Sharing**: Public and private snapshot sharing
-- **Versioning**: Track changes in snapshots over time
-
-## Service Architecture
-
-The server is designed as:
-- **Stateless**: Can be scaled horizontally
-- **Containerized**: Runs in Kubernetes or Docker
-- **Database-backed**: Persistent storage for metadata
-- **File storage**: Separate storage for snapshot files
-- **Load balanced**: Supports multiple instances
-
-## API Endpoints
-
-Core endpoints include:
-- `POST /snapshots` - Upload new snapshot
-- `GET /snapshots` - List snapshots
-- `GET /snapshots/{id}` - Get snapshot details
-- `GET /snapshots/{id}/download` - Download snapshot
-- `DELETE /snapshots/{id}` - Delete snapshot
-
-## Integration Points
-
-- **CLI Tool**: Receives uploaded snapshots
-- **Web UI**: Provides data for the frontend
-- **Database**: Stores metadata and user information
-- **File Storage**: Stores actual snapshot files
-- **Authentication**: Integrates with identity providers 
+- **High Throughput**: Optimized for concurrent snapshot uploads
+- **Fault Tolerance**: Circuit breakers and graceful degradation
+- **Observability**: Comprehensive logging and health checks
+- **Scalability**: Stateless design for horizontal scaling
+
+## Health & Monitoring
+
+- `/healthz` - Basic health check
+- `/readyz` - Readiness check (validates downstream services)
+- Structured logging with request tracing
+- Error reporting and recovery patterns
+
+## Configuration
+
+Environment-based configuration supporting:
+
+- Server timeouts and connection limits
+- Authentication providers and JWT settings
+- Rate limiting policies
+- Allowed origins for CORS
+- Service discovery endpoints
+