api-gateway/.docs/architecture.md

Architecture

System Overview

The SecNex API Gateway follows a modular architecture with clear separation of concerns. The system is built using the chi/v5 HTTP router and implements a middleware pipeline pattern.

┌─────────────────────────────────────────────────────────────┐
│                         Client Request                       │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                    Gateway (chi Router)                      │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Middleware Pipeline                      │  │
│  │  ┌────────────┐  ┌────────────┐  ┌──────────────┐   │  │
│  │  │ Request ID │→ │ Real IP    │→ │ Logger        │   │  │
│  │  └────────────┘  └────────────┘  └──────────────┘   │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                      Route Handler                          │
│  ┌──────────────────────────────────────────────────────┐  │
│  │            Per-Route Middleware Chain                 │  │
│  │  ┌────────────┐  ┌─────────┐  ┌──────────────┐      │  │
│  │  │ Strip      │→ │ WAF     │→ │ Auth         │      │  │
│  │  │ Prefix     │  │ Filter  │  │ Middleware   │      │  │
│  │  └────────────┘  └─────────┘  └──────────────┘      │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│              Reverse Proxy (httputil.ReverseProxy)          │
│                         │                                   │
│                         ▼                                   │
│                   Backend Service                           │
└─────────────────────────────────────────────────────────────┘

Component Architecture

Directory Structure

app/
├── main.go              # Application entry point
├── config/              # Configuration management
│   ├── config.go        # Config interface
│   ├── file.go          # File-based config loader
│   └── types.go         # Configuration type definitions
├── server/              # Core server components
│   ├── gateway.go       # Main gateway server
│   ├── routes.go        # Route handler creation
│   └── proxy.go         # Host-based virtual hosting
├── middlewares/         # HTTP middleware
│   ├── auth.go          # Authentication middleware
│   └── waf.go           # Web Application Firewall
├── handlers/            # Request handlers
│   └── route.go         # Route handlers (placeholder)
└── res/                 # HTTP responses
    └── error.go         # Error response utilities

Core Components

Gateway (server/gateway.go)

The Gateway is the main server component that:

• Initializes the chi router
• Applies global middleware (request_id, real_ip, logger)
• Registers route handlers
• Starts the HTTP server

Routes (server/routes.go)

The Routes component creates handlers for each configured route:

1. Finds the matching API backend target
2. Creates a reverse proxy using httputil.NewSingleHostReverseProxy
3. Optionally strips prefix from the request path
4. Applies middleware chain: WAF → Auth

Configuration (config/)

Configuration is loaded from YAML and provides:

• Gateway settings (host, port, features)
• Route definitions with security policies
• API backend targets
• Proxy configurations for virtual hosting

Middleware Chain

Global Middleware

Applied to all requests via chi middleware:

Feature	Description
request_id	Adds unique request ID to context
real_ip	Determines the real client IP
logger	Logs HTTP requests

Per-Route Middleware

Applied in order to each route handler:

1. StripPrefix - Removes specified prefix from request path before proxying
2. WAF - Filters requests based on HTTP method
3. Auth - Validates authentication credentials

Request Flow

1. Client Request → Gateway receives HTTP request
2. Global Middleware → Request ID, Real IP, Logging applied
3. Route Matching → Chi matches route pattern (e.g., /api/v1/dev/*)
4. Per-Route Middleware → StripPrefix → WAF → Auth
5. Reverse Proxy → Request forwarded to backend API
6. Response → Backend response returned to client

Authentication Flow

The authentication middleware supports path-based filtering:

┌─────────────────────┐
│   Include Set?      │
└──────────┬──────────┘
           │
     ┌─────┴─────┐
     │ Yes       │ No
     ▼           ▼
┌─────────┐  ┌─────────────┐
│ Match   │  │ Exclude     │
│ Include?│  │ Set?        │
└────┬────┘  └──────┬──────┘
     │              │
  ┌──┴──┐        ┌──┴──┐
  │Yes  │No      │Yes  │No
  ▼     ▼        ▼     ▼
┌────┐┌────┐  ┌────┐┌────┐
│Auth││Skip│  │Skip││Auth│
└────┘└────┘  └────┘└────┘

Configuration Flow

1. Load gateway.yaml via config.NewFileConfig()
2. Parse YAML into Configuration struct
3. Create Gateway with configuration
4. Create Routes from route definitions and API targets
5. Register handlers with chi router
6. Start HTTP server