# corazawaf/coraza-spoa architecture

> Architecture diagram of the GitHub repository corazawaf/coraza-spoa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/corazawaf/coraza-spoa
- Repository: https://github.com/corazawaf/coraza-spoa

## Overview

Coraza SPOA is a Go daemon that receives HAProxy SPOE messages, selects an application, and evaluates HTTP request and (optionally) response phases with Coraza. The principal path returns enforcement variables to HAProxy; response inspection correlates a later message to a cached request transaction. Configuration builds and reloads applications, while logging and Prometheus metrics expose outcomes. The README also documents rule-set compatibility, HAProxy integration, health/metrics endpoints, and operational deployment. Edges reflect the excerpts and README; unshown application internals are not expanded.

Main entry points: [`internal/agent.go`](https://github.com/corazawaf/coraza-spoa/blob/main/internal/agent.go) (SPOE dispatcher), [`main.go`](https://github.com/corazawaf/coraza-spoa/blob/main/main.go) (Daemon entry), [`internal/application.go`](https://github.com/corazawaf/coraza-spoa/blob/main/internal/application.go) (Request inspection), [`config.go`](https://github.com/corazawaf/coraza-spoa/blob/main/config.go) (Config reload)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Daemon runtime"]
  node_main["Daemon entry<br/>[main.go]"]
  node_agent["SPOE dispatcher<br/>[agent.go]"]
end

subgraph group_config["Configuration"]
  node_configread["Config loader<br/>[config.go]"]
  node_reload["Config reload<br/>[config.go]"]
end

subgraph group_waf["WAF processing"]
  node_application["WAF application<br/>[application.go]"]
  node_request["Request inspection<br/>[application.go]"]
  node_response["Response inspection<br/>[application.go]"]
  node_coraza{{"Coraza engine"}}
  node_ttlcache[("Transaction cache<br/>[ttlcache.go]")]
  node_rules["Coraza rulesets"]
end

subgraph group_observability["Observability"]
  node_metrics["WAF metrics<br/>[metrics.go]"]
  node_metricshttp["Metrics endpoint<br/>[main.go]"]
  node_logging["WAF logging<br/>[application.go]"]
end

node_haproxy(("HAProxy"))
node_prometheus(("Prometheus"))

node_haproxy -->|"sends SPOE"| node_agent
node_main -->|"loads config"| node_configread
node_main -->|"builds apps"| node_application
node_main -->|"serves messages"| node_agent
node_main -->|"starts endpoint"| node_metricshttp
node_main -->|"watches config"| node_reload
node_reload -->|"reloads file"| node_configread
node_reload -->|"replaces apps"| node_agent
node_agent -->|"dispatches request"| node_request
node_agent -->|"dispatches response"| node_response
node_request -->|"evaluates request"| node_coraza
node_response -->|"evaluates response"| node_coraza
node_application -.->|"loads rules"| node_rules
node_request -.->|"stores transaction"| node_ttlcache
node_response -->|"correlates transaction"| node_ttlcache
node_request -.->|"logs matches"| node_logging
node_response -.->|"logs matches"| node_logging
node_agent -->|"records handling"| node_metrics
node_metricshttp -->|"serves metrics"| node_prometheus
node_agent -->|"returns actions"| node_haproxy

click node_main "https://github.com/corazawaf/coraza-spoa/blob/main/main.go"
click node_agent "https://github.com/corazawaf/coraza-spoa/blob/main/internal/agent.go"
click node_configread "https://github.com/corazawaf/coraza-spoa/blob/main/config.go"
click node_reload "https://github.com/corazawaf/coraza-spoa/blob/main/config.go"
click node_application "https://github.com/corazawaf/coraza-spoa/blob/main/internal/application.go"
click node_request "https://github.com/corazawaf/coraza-spoa/blob/main/internal/application.go"
click node_response "https://github.com/corazawaf/coraza-spoa/blob/main/internal/application.go"
click node_ttlcache "https://github.com/corazawaf/coraza-spoa/blob/main/internal/ttlcache.go"
click node_metrics "https://github.com/corazawaf/coraza-spoa/blob/main/internal/metrics.go"
click node_metricshttp "https://github.com/corazawaf/coraza-spoa/blob/main/main.go"
click node_logging "https://github.com/corazawaf/coraza-spoa/blob/main/internal/application.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_agent toneBlue
class node_configread,node_reload toneAmber
class node_application,node_request,node_response,node_coraza,node_ttlcache,node_rules toneMint
class node_metrics,node_metricshttp,node_logging toneRose
class node_haproxy,node_prometheus toneIndigo
```

## Components

### Daemon runtime

- [Daemon entry](https://github.com/corazawaf/coraza-spoa/blob/main/main.go): `main.go`
- [SPOE dispatcher](https://github.com/corazawaf/coraza-spoa/blob/main/internal/agent.go): `internal/agent.go`

### Configuration

- [Config loader](https://github.com/corazawaf/coraza-spoa/blob/main/config.go): `config.go`
- [Config reload](https://github.com/corazawaf/coraza-spoa/blob/main/config.go): `config.go`

### WAF processing

- [WAF application](https://github.com/corazawaf/coraza-spoa/blob/main/internal/application.go): `internal/application.go`
- [Request inspection](https://github.com/corazawaf/coraza-spoa/blob/main/internal/application.go): `internal/application.go`
- [Response inspection](https://github.com/corazawaf/coraza-spoa/blob/main/internal/application.go): `internal/application.go`
- **Coraza engine**
- [Transaction cache](https://github.com/corazawaf/coraza-spoa/blob/main/internal/ttlcache.go): `internal/ttlcache.go`
- **Coraza rulesets**

### Observability

- [WAF metrics](https://github.com/corazawaf/coraza-spoa/blob/main/internal/metrics.go): `internal/metrics.go`
- [Metrics endpoint](https://github.com/corazawaf/coraza-spoa/blob/main/main.go): `main.go`
- [WAF logging](https://github.com/corazawaf/coraza-spoa/blob/main/internal/application.go): `internal/application.go`

### Other components

- **HAProxy**
- **Prometheus**

## Connections

- HAProxy → SPOE dispatcher: sends SPOE (evidence: `README.md`)
- Daemon entry → Config loader: loads config (evidence: `main.go`)
- Daemon entry → WAF application: builds apps
- Daemon entry → SPOE dispatcher: serves messages (evidence: `main.go`)
- Daemon entry → Metrics endpoint: starts endpoint (evidence: `main.go`)
- Daemon entry → Config reload: watches config (evidence: `main.go`)
- Config reload → Config loader: reloads file (evidence: `config.go`)
- Config reload → SPOE dispatcher: replaces apps (evidence: `config.go`)
- SPOE dispatcher → Request inspection: dispatches request (evidence: `internal/agent.go`)
- SPOE dispatcher → Response inspection: dispatches response (evidence: `internal/agent.go`)
- Request inspection → Coraza engine: evaluates request (evidence: `internal/application.go`)
- Response inspection → Coraza engine: evaluates response (evidence: `internal/application.go`)
- WAF application → Coraza rulesets: loads rules
- Request inspection → Transaction cache: stores transaction
- Response inspection → Transaction cache: correlates transaction (evidence: `internal/application.go`)
- Request inspection → WAF logging: logs matches (evidence: `internal/application.go`)
- Response inspection → WAF logging: logs matches (evidence: `internal/application.go`)
- SPOE dispatcher → WAF metrics: records handling (evidence: `internal/agent.go`)
- Metrics endpoint → Prometheus: serves metrics (evidence: `main.go`)
- SPOE dispatcher → HAProxy: returns actions (evidence: `internal/agent.go`)
