# codexeron/web-site-guard architecture

> Architecture diagram of the GitHub repository codexeron/web-site-guard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codexeron/web-site-guard
- Repository: https://github.com/codexeron/web-site-guard

## Overview

Web Site Guard is a FastAPI web-protection service. Its documented request workflow checks whitelist/blacklist, rate limits, bot signatures, WAF rules and login lockouts before forwarding accepted requests; responses receive security headers. Login records attempts and issues CSRF tokens, while honeypot hits are logged and trigger an IP block. The sampled middleware does not invoke geo blocking or CSRF validation. The README also describes upload scanning, TLS monitoring, anomaly detection, and broader logging/admin features, but their implementation files are absent from the supplied tree; those branches are shown without inferred wiring.

Main entry points: [`main.py`](https://github.com/codexeron/web-site-guard/blob/Codexeron/main.py) (FastAPI app), [`database.py`](https://github.com/codexeron/web-site-guard/blob/Codexeron/database.py) (Connection pool), [`database.sql`](https://github.com/codexeron/web-site-guard/blob/Codexeron/database.sql) (PostgreSQL), [`waf.py`](https://github.com/codexeron/web-site-guard/blob/Codexeron/waf.py) (WAF scanning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_request["Request protection"]
  node_main["FastAPI app<br/>[main.py]"]
  node_ip["IP lists<br/>[ip_manager.py]"]
  node_rate["Rate limiter<br/>[rate_limiter.py]"]
  node_bot["Bot detection<br/>[bot_guard.py]"]
  node_waf["WAF scanning<br/>[waf.py]"]
  node_headers["Security headers<br/>[headers_guard.py]"]
  node_geo["Geo rules<br/>[geo_guard.py]"]
end

subgraph group_identity["Identity and traps"]
  node_brute["Login protection<br/>[bruteforce.py]"]
  node_csrf["CSRF tokens<br/>[csrf.py]"]
  node_honeypot["Honeypot endpoint<br/>[main.py]"]
end

subgraph group_storage["Data and configuration"]
  node_database[("PostgreSQL<br/>[database.sql]")]
  node_pool["Connection pool<br/>[database.py]"]
  node_config["Runtime config<br/>[config.py]"]
end

subgraph group_additional["Additional protections"]
  node_uploads["Upload scanning"]
  node_tls["TLS monitoring"]
  node_anomaly["Anomaly detection"]
  node_logs[("Request and audit logs")]
end

node_client(("HTTP client"))
node_app(("Protected application"))

node_client -->|"sends HTTP"| node_main
node_main -->|"checks lists"| node_ip
node_main -->|"checks limit"| node_rate
node_main -->|"checks agent"| node_bot
node_main -->|"scans payload"| node_waf
node_main -->|"checks lockout"| node_brute
node_main -->|"forwards request"| node_app
node_main -->|"applies headers"| node_headers
node_main -->|"records login"| node_brute
node_main -->|"issues token"| node_csrf
node_main -->|"serves route"| node_honeypot
node_main -->|"loads rules"| node_geo
node_main -->|"opens pool"| node_pool
node_ip -->|"gets connection"| node_pool
node_rate -->|"gets connection"| node_pool
node_bot -->|"loads signatures"| node_pool
node_waf -->|"loads rules"| node_pool
node_waf -->|"writes threats"| node_pool
node_brute -->|"reads and writes"| node_pool
node_csrf -->|"reads and writes"| node_pool
node_geo -->|"loads rules"| node_pool
node_honeypot -->|"gets connection"| node_pool
node_pool -->|"queries"| node_database
node_ip -->|"reads and writes lists"| node_database
node_rate -->|"updates counters"| node_database
node_bot -->|"reads signatures"| node_database
node_waf -->|"reads rules and writes events"| node_database
node_brute -->|"reads attempts"| node_database
node_csrf -->|"stores tokens"| node_database
node_geo -->|"reads rules"| node_database
node_honeypot -->|"writes hits"| node_database
node_config -->|"provides settings"| node_pool

click node_main "https://github.com/codexeron/web-site-guard/blob/Codexeron/main.py"
click node_ip "https://github.com/codexeron/web-site-guard/blob/Codexeron/ip_manager.py"
click node_rate "https://github.com/codexeron/web-site-guard/blob/Codexeron/rate_limiter.py"
click node_bot "https://github.com/codexeron/web-site-guard/blob/Codexeron/bot_guard.py"
click node_waf "https://github.com/codexeron/web-site-guard/blob/Codexeron/waf.py"
click node_headers "https://github.com/codexeron/web-site-guard/blob/Codexeron/headers_guard.py"
click node_brute "https://github.com/codexeron/web-site-guard/blob/Codexeron/bruteforce.py"
click node_csrf "https://github.com/codexeron/web-site-guard/blob/Codexeron/csrf.py"
click node_honeypot "https://github.com/codexeron/web-site-guard/blob/Codexeron/main.py"
click node_geo "https://github.com/codexeron/web-site-guard/blob/Codexeron/geo_guard.py"
click node_database "https://github.com/codexeron/web-site-guard/blob/Codexeron/database.sql"
click node_pool "https://github.com/codexeron/web-site-guard/blob/Codexeron/database.py"
click node_config "https://github.com/codexeron/web-site-guard/blob/Codexeron/config.py"

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_ip,node_rate,node_bot,node_waf,node_headers,node_geo,node_client toneBlue
class node_brute,node_csrf,node_honeypot toneAmber
class node_database,node_pool,node_config toneMint
class node_uploads,node_tls,node_anomaly,node_logs toneRose
class node_app toneIndigo
```

## Components

### Request protection

- [FastAPI app](https://github.com/codexeron/web-site-guard/blob/Codexeron/main.py): `main.py`
- [IP lists](https://github.com/codexeron/web-site-guard/blob/Codexeron/ip_manager.py): `ip_manager.py`
- [Rate limiter](https://github.com/codexeron/web-site-guard/blob/Codexeron/rate_limiter.py): `rate_limiter.py`
- [Bot detection](https://github.com/codexeron/web-site-guard/blob/Codexeron/bot_guard.py): `bot_guard.py`
- [WAF scanning](https://github.com/codexeron/web-site-guard/blob/Codexeron/waf.py): `waf.py`
- [Security headers](https://github.com/codexeron/web-site-guard/blob/Codexeron/headers_guard.py): `headers_guard.py`
- [Geo rules](https://github.com/codexeron/web-site-guard/blob/Codexeron/geo_guard.py): `geo_guard.py`

### Identity and traps

- [Login protection](https://github.com/codexeron/web-site-guard/blob/Codexeron/bruteforce.py): `bruteforce.py`
- [CSRF tokens](https://github.com/codexeron/web-site-guard/blob/Codexeron/csrf.py): `csrf.py`
- [Honeypot endpoint](https://github.com/codexeron/web-site-guard/blob/Codexeron/main.py): `main.py`

### Data and configuration

- [PostgreSQL](https://github.com/codexeron/web-site-guard/blob/Codexeron/database.sql): `database.sql`
- [Connection pool](https://github.com/codexeron/web-site-guard/blob/Codexeron/database.py): `database.py`
- [Runtime config](https://github.com/codexeron/web-site-guard/blob/Codexeron/config.py): `config.py`

### Additional protections

- **Upload scanning**
- **TLS monitoring**
- **Anomaly detection**
- **Request and audit logs**

### Other components

- **HTTP client**
- **Protected application**

## Connections

- HTTP client → FastAPI app: sends HTTP
- FastAPI app → IP lists: checks lists
- FastAPI app → Rate limiter: checks limit
- FastAPI app → Bot detection: checks agent
- FastAPI app → WAF scanning: scans payload
- FastAPI app → Login protection: checks lockout
- FastAPI app → Protected application: forwards request
- FastAPI app → Security headers: applies headers
- FastAPI app → Login protection: records login
- FastAPI app → CSRF tokens: issues token
- FastAPI app → Honeypot endpoint: serves route
- FastAPI app → Geo rules: loads rules
- FastAPI app → Connection pool: opens pool
- IP lists → Connection pool: gets connection
- Rate limiter → Connection pool: gets connection
- Bot detection → Connection pool: loads signatures
- WAF scanning → Connection pool: loads rules
- WAF scanning → Connection pool: writes threats
- Login protection → Connection pool: reads and writes
- CSRF tokens → Connection pool: reads and writes
- Geo rules → Connection pool: loads rules
- Honeypot endpoint → Connection pool: gets connection
- Connection pool → PostgreSQL: queries
- IP lists → PostgreSQL: reads and writes lists
- Rate limiter → PostgreSQL: updates counters
- Bot detection → PostgreSQL: reads signatures
- WAF scanning → PostgreSQL: reads rules and writes events
- Login protection → PostgreSQL: reads attempts
- CSRF tokens → PostgreSQL: stores tokens
- Geo rules → PostgreSQL: reads rules
- Honeypot endpoint → PostgreSQL: writes hits
- Runtime config → Connection pool: provides settings