# 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