# wallarm/api-firewall architecture

> Architecture diagram of the GitHub repository wallarm/api-firewall, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wallarm/api-firewall
- Repository: https://github.com/wallarm/api-firewall

## Overview

##### Project Type and Purpose
- This is an open‐source, high‐performance API Firewall/proxy written in Go. It validates REST (OpenAPI) and GraphQL requests & responses against provided schemas, enforces a positive‐security model, and can run in PROXY, API, or GRAPHQL modes.

##### File Structure Analysis
- **cmd/api-firewall**: entrypoint (main.go) + HTTP(GraphQL) handlers + proxy and updater subcommands + benchmarks/tests.
- **internal/**: core implementation broken into layers:
- config (app settings, servers, schemas)
- mid (HTTP middleware: logging, ModSecurity, allow/deny lists)
- platform (ports/adapters): storage (databases for schemas, tokens, lists), proxy (fasthttp-based HTTP & WebSocket forwarding, DNS cache), oauth2 introspection, metrics (Prometheus), router (Chi mux), validator (OpenAPI/GraphQL decoder/encoder).
- web (HTTP server adaptor/tracing/response helpers).
- version.
- **pkg/APIMode**: standalone API‐mode library.
- **demo/**: Docker Compose & Kubernetes examples showing real backends (httpbin, vulnerable GraphQL app), volumes, manifests, scripts.
- **helm/**: Helm chart for Kubernetes deployment.
- **docs/**: guides & configuration references.
- Root: Dockerfile, Makefile, GitHub workflows for CI/CD, mkdocs, license.

##### Key Architecture Insights from README
- Reverse proxy with built‐in schema validator.
- Supports multiple Content‐Types & protocols (REST, GraphQL HTTP & WS).
- Pluggable ModSecurity rules via Coraza/OWASP CRS.
- Extensible storage for allow/deny lists, token denylist, schema loader/updater.
- Metrics exported to Prometheus.

a. Main Components
- **Clients (External)**: REST clients, GraphQL clients, browsers (WebSocket)
- **API Firewall Service** (single container/pod) comprising:
1. **HTTP Server Layer** (fasthttp)
2. **Router** (Chi-based multiplexer)
3. **Middleware** (logging, CORS, allow/deny lists, ModSecurity)
4. **Schema Loader/Updater** (OpenAPI/GraphQL loader from DB or file)
5. **Validator** (request/response against schema)
6. **Proxy Core**
- HTTP Proxy (fasthttp ReverseProxy)
- WebSocket Proxy
- DNS Cache
7. **OAuth2 Introspection** (JWT & introspection calls)
8. **Metrics Exporter** (Prometheus client)
9. **Storage Adapters**
- SQLite/PostgreSQL for schemas, token denylist, allow/deny lists
- File‐based fallback
- **Upstream Backends** (configurable)
- REST API (e.g., httpbin)
- GraphQL server (e.g., demo app)
- **External Services**
- OAuth2 Auth Server (optional)
- Prometheus / Grafana

b. Relationships & Data Flow
1. Client → HTTP Server → Router → Middleware chain
2. Middleware calls Schema Loader on startup/updates; passes request to Validator
3. Validator approves or rejects; logs or blocks
4. On approval: Proxy Core forwards to Upstream Backend
5. Response travels back: Proxy Core → Validator → Middleware → Client
6. Metrics & logs emitted throughout
7. Updater component refreshes schema DB from file system or remote

c. Architectural Patterns & Principles
- **Layered Architecture**: clear separation of config, middleware, validation, proxy, storage.
- **Ports & Adapters (Hexagonal)**: `internal/platform` defines interfaces; `storage`, `proxy`, `oauth2` are adapters.
- **Modular Handlers**: separate handlers for API mode, PROXY mode, GraphQL HTTP & WS.
- **Plug-able Schemas & Rules**: dynamic loader/updater for OpenAPI, GraphQL, ModSecurity.

d. Key Technologies
- Go + fasthttp for ultra‐fast HTTP server & proxy
- Chi router for request routing
- Coraza (ModSecurity) for attack signature enforcement
- SQLite (via storage adapters) or file storage for local DBs
- Prometheus client library for metrics
- Docker, Docker Compose, Helm/Kubernetes for deployment

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    ClientREST["REST Client"]:::external
    ClientGraphQL["GraphQL Client/WebSocket"]:::external

    %% Ingress/Server Layer
    subgraph "Ingress/Server Layer"
        HTTPServer["HTTP Server Layer"]:::ingress
        Router["Router"]:::ingress
        APIHandler["API, GraphQL, Proxy Handlers"]:::ingress
    end

    %% Validation & Middleware Layer
    subgraph "Validation & Middleware Layer"
        Mid["Middleware\n(logging, CORS, allow/deny lists, ModSecurity)"]:::validation
        Loader["Schema Loader"]:::validation
        UpdaterAdapter["Schema Updater Adapter"]:::validation
        UpdaterCLI_API["Updater CLI (API)"]:::validation
        UpdaterCLI_Proxy["Updater CLI (Proxy)"]:::validation
        Validator["Validator\n(OpenAPI & GraphQL)"]:::validation
    end

    %% Proxy & Routing Layer
    subgraph "Proxy & Routing Layer"
        Proxy["Proxy Core\n(HTTP ReverseProxy, WS, DNS Cache)"]:::proxy
        OAuth2["OAuth2 Introspection"]:::proxy
    end

    %% Storage & Persistence Layer
    subgraph "Storage & Persistence Layer"
        StorageAdapters["Storage Adapters"]:::storage
        SchemaDB["Schema DB"]:::storage
        TokenDB["Token Denylist DB"]:::storage
        FileStorage["File-based Fallback"]:::storage
    end

    %% Supporting Platform Components
    subgraph "Platform Services"
        Web["Web Adapter & Tracing"]:::platform
        Config["Configuration"]:::platform
        Version["Version Info"]:::platform
    end

    %% API-Mode Library
    subgraph "API-Mode Library"
        APIMode["pkg/APIMode"]:::library
    end

    %% Upstream & External Services
    OAuthServer["OAuth2 Auth Server"]:::external
    Prometheus["Prometheus"]:::external
    Grafana["Grafana"]:::external
    UpstreamREST["Upstream REST API"]:::external
    UpstreamGraphQL["Upstream GraphQL Server"]:::external

    %% Connections
    ClientREST -->|"HTTP request"| HTTPServer
    ClientGraphQL -->|"GraphQL HTTP/WS"| HTTPServer

    HTTPServer --> Router
    Router --> Mid
    Mid --> Loader
    Loader --> Validator
    Validator --> Proxy
    Proxy --> UpstreamREST
    Proxy --> UpstreamGraphQL

    UpstreamREST --> Proxy
    UpstreamGraphQL --> Proxy
    Proxy --> Validator
    Validator --> Mid
    Mid --> HTTPServer
    HTTPServer --> ClientREST
    HTTPServer --> ClientGraphQL

    %% Metrics Flow
    HTTPServer -->|"metrics"| Prometheus
    Mid -->|"metrics"| Prometheus
    Proxy -->|"metrics"| Prometheus
    Prometheus --> Grafana

    %% Schema Updater
    UpdaterAdapter --> StorageAdapters
    UpdaterCLI_API --> StorageAdapters
    UpdaterCLI_Proxy --> StorageAdapters

    StorageAdapters --> SchemaDB
    StorageAdapters --> TokenDB
    StorageAdapters --> FileStorage

    %% OAuth2 Flow
    Proxy --> OAuth2
    OAuth2 --> OAuthServer
    OAuth2 --> StorageAdapters

    %% Platform & Config
    HTTPServer --> Web
    HTTPServer --> Config
    HTTPServer --> Version

    %% API-Mode usage
    APIMode --> Validator
    APIMode --> Loader

    %% Click Events
    click HTTPServer "https://github.com/wallarm/api-firewall/blob/main/cmd/api-firewall/main.go"
    click APIHandler "https://github.com/wallarm/api-firewall/tree/main/cmd/api-firewall/internal/handlers"
    click Router "https://github.com/wallarm/api-firewall/tree/main/internal/platform/router"
    click Mid "https://github.com/wallarm/api-firewall/tree/main/internal/mid"
    click Loader "https://github.com/wallarm/api-firewall/blob/main/internal/platform/loader/loader.go"
    click UpdaterAdapter "https://github.com/wallarm/api-firewall/blob/main/internal/platform/storage/updater/updater.go"
    click UpdaterCLI_API "https://github.com/wallarm/api-firewall/blob/main/cmd/api-firewall/internal/handlers/api/updater.go"
    click UpdaterCLI_Proxy "https://github.com/wallarm/api-firewall/blob/main/cmd/api-firewall/internal/handlers/proxy/updater.go"
    click Validator "https://github.com/wallarm/api-firewall/tree/main/internal/platform/validator"
    click Proxy "https://github.com/wallarm/api-firewall/tree/main/internal/platform/proxy"
    click OAuth2 "https://github.com/wallarm/api-firewall/tree/main/internal/platform/oauth2"
    click Prometheus "https://github.com/wallarm/api-firewall/blob/main/internal/platform/metrics/prometheus.go"
    click StorageAdapters "https://github.com/wallarm/api-firewall/tree/main/internal/platform/storage"
    click APIMode "https://github.com/wallarm/api-firewall/tree/main/pkg/APIMode"
    click Web "https://github.com/wallarm/api-firewall/tree/main/internal/platform/web"
    click Config "https://github.com/wallarm/api-firewall/tree/main/internal/config"
    click Version "https://github.com/wallarm/api-firewall/blob/main/internal/version/version.go"

    %% Styles
    classDef ingress fill:#e0f7ff,stroke:#000,stroke-width:1px
    classDef validation fill:#e0ffe0,stroke:#000,stroke-width:1px
    classDef proxy fill:#ffe0b2,stroke:#000,stroke-width:1px
    classDef storage fill:#e0e0e0,stroke:#000,stroke-width:1px
    classDef external fill:#e1bee7,stroke:#000,stroke-width:1px
    classDef library fill:#f3e5f5,stroke:#000,stroke-width:1px
    classDef platform fill:#f0f4c3,stroke:#000,stroke-width:1px
```
