# antonioribeiro/firewall architecture

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

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

## Overview

Firewall is a Laravel soft-firewall package for IP-, host-, range-, and country-based access control. A request enters through route middleware, which applies blacklist or whitelist policy through the Firewall facade/service and returns a block or redirect when required. Separate attack detection counts requests and can blacklist offenders and emit notifications. The README also documents list management, session blocking, GeoIP, and database/array/file-backed lists. Some command and session implementations are not shown, so those documented capabilities are represented without speculative call edges.

Main entry points: [`src/Firewall.php`](https://github.com/antonioribeiro/firewall/blob/master/src/Firewall.php) (Firewall service), [`src/Repositories/DataRepository.php`](https://github.com/antonioribeiro/firewall/blob/master/src/Repositories/DataRepository.php) (Data repository), [`src/Support/AttackBlocker.php`](https://github.com/antonioribeiro/firewall/blob/master/src/Support/AttackBlocker.php) (Attack detector), [`src/Middleware/FilterMiddleware.php`](https://github.com/antonioribeiro/firewall/blob/master/src/Middleware/FilterMiddleware.php) (Route middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Request access control"]
  node_middleware["Route middleware"]
  node_blackmw["Blacklist middleware"]
  node_whitemw["Whitelist middleware"]
  node_blackfilter["Blacklist filter<br/>[Blacklist.php]"]
  node_whitefilter["Whitelist filter<br/>[Whitelist.php]"]
end

subgraph group_domain["Firewall domain"]
  node_firewall["Firewall service<br/>[Firewall.php]"]
  node_responder["Response builder<br/>[Responder.php]"]
  node_ipaddress["IP address handling<br/>[IpAddress.php]"]
  node_instances["Service instances"]
end

subgraph group_storage["Lists and GeoIP"]
  node_data["Data repository<br/>[DataRepository.php]"]
  node_iplists[("IP list store<br/>[IpList.php]")]
  node_countries["Country lookup<br/>[Countries.php]"]
  node_cache[("Attack cache<br/>[Cache.php]")]
  node_messages["Message repository<br/>[Message.php]"]
end

subgraph group_attacks["Attack response"]
  node_attackmw["Attack middleware<br/>[BlockAttacks.php]"]
  node_attackblocker["Attack detector<br/>[AttackBlocker.php]"]
  node_attackevent["Attack event<br/>[AttackDetected.php]"]
  node_listener["Admin notifier<br/>[NotifyAdmins.php]"]
  node_notification["Notification dispatch<br/>[Notification.php]"]
  node_slack["Slack channel<br/>[Slack.php]"]
  node_mail["Mail channel<br/>[Mail.php]"]
end

node_client(("HTTP client"))

node_client -->|"sends request"| node_middleware
node_middleware -.->|"dispatches to"| node_blackmw
node_middleware -.->|"dispatches to"| node_whitemw
node_blackmw -->|"applies"| node_blackfilter
node_whitemw -->|"applies"| node_whitefilter
node_blackfilter -->|"checks list"| node_firewall
node_whitefilter -->|"checks whitelist"| node_firewall
node_whitefilter -->|"builds response"| node_responder
node_firewall -->|"delegates list operations"| node_data
node_firewall -->|"builds block response"| node_responder
node_data -->|"delegates list operations"| node_iplists
node_data -->|"looks up countries"| node_countries
node_data -->|"validates addresses"| node_ipaddress
node_firewall -->|"checks attack state"| node_attackblocker
node_attackmw -->|"checks attack"| node_firewall
node_attackblocker -->|"stores request counts"| node_cache
node_attackblocker -->|"blacklists offenders"| node_firewall
node_attackblocker -->|"emits event"| node_attackevent
node_attackevent -->|"notifies listener"| node_listener
node_listener -->|"creates notification"| node_notification
node_notification -->|"dispatches channel"| node_slack
node_notification -->|"dispatches channel"| node_mail
node_attackblocker -->|"builds attack response"| node_responder
node_instances -.->|"resolves binding"| node_data
node_data -->|"supports configured list sources"| node_iplists

click node_middleware "https://github.com/antonioribeiro/firewall/blob/master/src/Middleware/FilterMiddleware.php"
click node_blackmw "https://github.com/antonioribeiro/firewall/blob/master/src/Middleware/FirewallBlacklist.php"
click node_whitemw "https://github.com/antonioribeiro/firewall/blob/master/src/Middleware/FirewallWhitelist.php"
click node_blackfilter "https://github.com/antonioribeiro/firewall/blob/master/src/Filters/Blacklist.php"
click node_whitefilter "https://github.com/antonioribeiro/firewall/blob/master/src/Filters/Whitelist.php"
click node_firewall "https://github.com/antonioribeiro/firewall/blob/master/src/Firewall.php"
click node_responder "https://github.com/antonioribeiro/firewall/blob/master/src/Support/Responder.php"
click node_ipaddress "https://github.com/antonioribeiro/firewall/blob/master/src/Support/IpAddress.php"
click node_instances "https://github.com/antonioribeiro/firewall/blob/master/src/Support/ServiceInstances.php"
click node_data "https://github.com/antonioribeiro/firewall/blob/master/src/Repositories/DataRepository.php"
click node_iplists "https://github.com/antonioribeiro/firewall/blob/master/src/Repositories/IpList.php"
click node_countries "https://github.com/antonioribeiro/firewall/blob/master/src/Repositories/Countries.php"
click node_cache "https://github.com/antonioribeiro/firewall/blob/master/src/Repositories/Cache/Cache.php"
click node_messages "https://github.com/antonioribeiro/firewall/blob/master/src/Repositories/Message.php"
click node_attackmw "https://github.com/antonioribeiro/firewall/blob/master/src/Middleware/BlockAttacks.php"
click node_attackblocker "https://github.com/antonioribeiro/firewall/blob/master/src/Support/AttackBlocker.php"
click node_attackevent "https://github.com/antonioribeiro/firewall/blob/master/src/Events/AttackDetected.php"
click node_listener "https://github.com/antonioribeiro/firewall/blob/master/src/Listeners/NotifyAdmins.php"
click node_notification "https://github.com/antonioribeiro/firewall/blob/master/src/Notifications/Notification.php"
click node_slack "https://github.com/antonioribeiro/firewall/blob/master/src/Notifications/Channels/Slack.php"
click node_mail "https://github.com/antonioribeiro/firewall/blob/master/src/Notifications/Channels/Mail.php"

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_middleware,node_blackmw,node_whitemw,node_blackfilter,node_whitefilter,node_client toneBlue
class node_firewall,node_responder,node_ipaddress,node_instances toneAmber
class node_data,node_iplists,node_countries,node_cache,node_messages toneMint
class node_attackmw,node_attackblocker,node_attackevent,node_listener,node_notification,node_slack,node_mail toneRose
```

## Components

### Request access control

- [Route middleware](https://github.com/antonioribeiro/firewall/blob/master/src/Middleware/FilterMiddleware.php): `src/Middleware/FilterMiddleware.php`
- [Blacklist middleware](https://github.com/antonioribeiro/firewall/blob/master/src/Middleware/FirewallBlacklist.php): `src/Middleware/FirewallBlacklist.php`
- [Whitelist middleware](https://github.com/antonioribeiro/firewall/blob/master/src/Middleware/FirewallWhitelist.php): `src/Middleware/FirewallWhitelist.php`
- [Blacklist filter](https://github.com/antonioribeiro/firewall/blob/master/src/Filters/Blacklist.php): `src/Filters/Blacklist.php`
- [Whitelist filter](https://github.com/antonioribeiro/firewall/blob/master/src/Filters/Whitelist.php): `src/Filters/Whitelist.php`

### Firewall domain

- [Firewall service](https://github.com/antonioribeiro/firewall/blob/master/src/Firewall.php): `src/Firewall.php`
- [Response builder](https://github.com/antonioribeiro/firewall/blob/master/src/Support/Responder.php): `src/Support/Responder.php`
- [IP address handling](https://github.com/antonioribeiro/firewall/blob/master/src/Support/IpAddress.php): `src/Support/IpAddress.php`
- [Service instances](https://github.com/antonioribeiro/firewall/blob/master/src/Support/ServiceInstances.php): `src/Support/ServiceInstances.php`

### Lists and GeoIP

- [Data repository](https://github.com/antonioribeiro/firewall/blob/master/src/Repositories/DataRepository.php): `src/Repositories/DataRepository.php`
- [IP list store](https://github.com/antonioribeiro/firewall/blob/master/src/Repositories/IpList.php): `src/Repositories/IpList.php`
- [Country lookup](https://github.com/antonioribeiro/firewall/blob/master/src/Repositories/Countries.php): `src/Repositories/Countries.php`
- [Attack cache](https://github.com/antonioribeiro/firewall/blob/master/src/Repositories/Cache/Cache.php): `src/Repositories/Cache/Cache.php`
- [Message repository](https://github.com/antonioribeiro/firewall/blob/master/src/Repositories/Message.php): `src/Repositories/Message.php`

### Attack response

- [Attack middleware](https://github.com/antonioribeiro/firewall/blob/master/src/Middleware/BlockAttacks.php): `src/Middleware/BlockAttacks.php`
- [Attack detector](https://github.com/antonioribeiro/firewall/blob/master/src/Support/AttackBlocker.php): `src/Support/AttackBlocker.php`
- [Attack event](https://github.com/antonioribeiro/firewall/blob/master/src/Events/AttackDetected.php): `src/Events/AttackDetected.php`
- [Admin notifier](https://github.com/antonioribeiro/firewall/blob/master/src/Listeners/NotifyAdmins.php): `src/Listeners/NotifyAdmins.php`
- [Notification dispatch](https://github.com/antonioribeiro/firewall/blob/master/src/Notifications/Notification.php): `src/Notifications/Notification.php`
- [Slack channel](https://github.com/antonioribeiro/firewall/blob/master/src/Notifications/Channels/Slack.php): `src/Notifications/Channels/Slack.php`
- [Mail channel](https://github.com/antonioribeiro/firewall/blob/master/src/Notifications/Channels/Mail.php): `src/Notifications/Channels/Mail.php`

### Other components

- **HTTP client**

## Connections

- HTTP client → Route middleware: sends request (evidence: `readme.md`)
- Route middleware → Blacklist middleware: dispatches to (evidence: `src/Middleware/FirewallBlacklist.php`)
- Route middleware → Whitelist middleware: dispatches to (evidence: `src/Middleware/FirewallWhitelist.php`)
- Blacklist middleware → Blacklist filter: applies (evidence: `src/Middleware/FirewallBlacklist.php`)
- Whitelist middleware → Whitelist filter: applies (evidence: `src/Middleware/FirewallWhitelist.php`)
- Blacklist filter → Firewall service: checks list (evidence: `src/Filters/Blacklist.php`)
- Whitelist filter → Firewall service: checks whitelist (evidence: `src/Filters/Whitelist.php`)
- Whitelist filter → Response builder: builds response (evidence: `src/Filters/Whitelist.php`)
- Firewall service → Data repository: delegates list operations (evidence: `src/Firewall.php`)
- Firewall service → Response builder: builds block response (evidence: `src/Firewall.php`)
- Data repository → IP list store: delegates list operations (evidence: `src/Repositories/DataRepository.php`)
- Data repository → Country lookup: looks up countries (evidence: `src/Repositories/DataRepository.php`)
- Data repository → IP address handling: validates addresses (evidence: `src/Repositories/DataRepository.php`)
- Firewall service → Attack detector: checks attack state (evidence: `src/Firewall.php`)
- Attack middleware → Firewall service: checks attack (evidence: `src/Middleware/BlockAttacks.php`)
- Attack detector → Attack cache: stores request counts (evidence: `src/Support/AttackBlocker.php`)
- Attack detector → Firewall service: blacklists offenders (evidence: `src/Support/AttackBlocker.php`)
- Attack detector → Attack event: emits event (evidence: `src/Support/AttackBlocker.php`)
- Attack event → Admin notifier: notifies listener (evidence: `src/Listeners/NotifyAdmins.php`)
- Admin notifier → Notification dispatch: creates notification (evidence: `src/Listeners/NotifyAdmins.php`)
- Notification dispatch → Slack channel: dispatches channel (evidence: `src/Notifications/Notification.php`)
- Notification dispatch → Mail channel: dispatches channel (evidence: `src/Notifications/Notification.php`)
- Attack detector → Response builder: builds attack response (evidence: `src/Support/AttackBlocker.php`)
- Service instances → Data repository: resolves binding (evidence: `src/Repositories/DataRepository.php`)
- Data repository → IP list store: supports configured list sources (evidence: `readme.md`)
