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)                       │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Global Middleware Pipeline              │  │
│  │  ┌────────────┐  ┌────────────┐  ┌──────────────┐    │  │
│  │  │ Request ID │→ │ Real IP    │→ │ Logger       │    │  │
│  │  └────────────┘  └────────────┘  └──────────────┘    │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────┬──────────────────────────────────┘
                          │
                          ▼
┌────────────────────────────────────────────────────────────┐
│                      Route Handler                         │
│  ┌──────────────────────────────────────────────────────┐  │
│  │            Per-Route Middleware Chain                │  │
│  │  ┌────────────┐  ┌──────────────┐                    │  │
│  │  │ Strip      │→ │ Reverse      │                    │  │
│  │  │ Prefix     │  │ Proxy        │                    │  │
│  │  └────────────┘  └──────────────┘                    │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────┬──────────────────────────────────┘
                          │
                          ▼
┌────────────────────────────────────────────────────────────┐
│              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
│   └── database.go      # Database configuration
├── server/              # Core server components
│   ├── gateway.go       # Main gateway server
│   ├── routes.go        # Route registration
│   ├── api.go           # API definitions
│   ├── host.go          # Host definitions
│   └── target.go        # Target (backend) definitions
├── middlewares/         # HTTP middleware
│   ├── host.go          # Host logging middleware
│   └── logger.go        # Structured logging middleware
└── utils/               # Utility functions

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, host)
• Configures proxy directors for each API
• Registers route handlers
• Starts the HTTP server

Routes (server/routes.go)

The Routes component handles:

• Creating route handlers from configuration
• Applying strip prefix middleware
• Registering routes with chi router (method-agnostic)
• Connecting routes to API backends

API (server/api.go)

API definitions that:

• Link hosts to backend targets
• Implement http.Handler interface for proxying
• Delegate requests to the reverse proxy

Hosts (server/host.go)

Host definitions for:

• Virtual hosting support
• Domain-based routing
• Host header validation

Targets (server/target.go)

Target (backend) definitions that:

• Store backend service URLs
• Create httputil.ReverseProxy instances
• Handle proxy configuration

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 from headers
logger	Logs HTTP requests with structured JSON output
host	Logs the host header for each request

Per-Route Middleware

Applied to each route handler:

1. StripPrefix - Removes specified prefix from request path before proxying

Request Flow

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

Configuration Flow

1. Load gateway.yaml via config.NewFile()
2. Parse YAML into Configuration struct
3. Create Hosts from configuration
4. Create Targets from configuration
5. Create APIs (linking Hosts to Targets)
6. Create Routes (linking Routes to APIs)
7. Initialize Gateway with all components
8. Configure proxy directors
9. Register routes with chi router
10. Start HTTP server

Logging

The gateway uses structured JSON logging via masterlog:

• HTTP Request Logging - method, path, status, duration, host, IP
• Gateway Events - startup, route registration, proxy configuration
• Sensitive Field Pseudonymization - user_id, email, ip fields are pseudonymized

Example log output:

{
  "level": "info",
  "msg": "HTTP Request",
  "method": "GET",
  "path": "/api/v1/users",
  "status": 200,
  "duration": "45ms",
  "host": "localhost:8080",
  "ip": "127.0.0.1:52342"
}