# mrrfv/cloudflare-gateway-pihole-scripts architecture

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

- Interactive diagram: https://gitdiagram.com/mrrfv/cloudflare-gateway-pihole-scripts
- Repository: https://github.com/mrrfv/cloudflare-gateway-pihole-scripts

## Overview

CGPS downloads or accepts blocklists and allowlists, normalizes and filters their domains, then synchronizes Cloudflare Gateway lists and blocking rules. Separate scripts handle deletion and list defragmentation; optional SNI filtering and notifications extend those operations. The graph reflects calls shown in excerpts and documented capabilities; some internal API behavior is only partially sampled, so uncertain connections are omitted.

Main entry points: [`lib/utils.js`](https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/lib/utils.js) (Retry and notifications), [`cf_list_create.js`](https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/cf_list_create.js) (Clean and reconcile domains), [`download_lists.js`](https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/download_lists.js) (Download lists), [`lib/api.js`](https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/lib/api.js) (Gateway API operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Filter inputs"]
  node_download["Download lists<br/>[download_lists.js]"]
  node_local_lists["Local filter files<br/>[download_lists.js]"]
end

subgraph group_processing["Domain processing"]
  node_process_lists["Clean and reconcile domains<br/>[cf_list_create.js]"]
end

subgraph group_gateway["Gateway management"]
  node_gateway_lists[("Gateway lists<br/>[api.js]")]
  node_gateway_rules_create["Create blocking rules"]
  node_gateway_rules_delete["Delete blocking rules"]
  node_gateway_lists_delete["Delete filter lists<br/>[cf_list_delete.js]"]
  node_defragment["Defragment lists<br/>[cf_defragment.js]"]
  node_api_client["Gateway API operations<br/>[api.js]"]
end

subgraph group_runtime["Shared runtime"]
  node_download_helpers["File downloads<br/>[utils.js]"]
  node_domain_helpers["Domain normalization<br/>[helpers.js]"]
  node_domain_utils["Domain utilities<br/>[utils.js]"]
  node_request_helper["Authenticated requests<br/>[helpers.js]"]
  node_http_utils["Retry and notifications<br/>[utils.js]"]
end

node_operator(("Operator"))
node_list_sources(("List sources"))
node_cloudflare[("Cloudflare Gateway")]
node_webhook(("Notification webhook"))

node_operator -->|"runs"| node_download
node_operator -->|"runs"| node_process_lists
node_operator -->|"runs"| node_gateway_rules_create
node_operator -->|"runs"| node_gateway_rules_delete
node_operator -->|"runs"| node_gateway_lists_delete
node_operator -->|"runs"| node_defragment
node_list_sources -->|"provides URLs"| node_download
node_download -->|"downloads through"| node_download_helpers
node_download_helpers -->|"fetches files"| node_list_sources
node_download -->|"writes"| node_local_lists
node_local_lists -->|"reads"| node_process_lists
node_process_lists -->|"normalizes with"| node_domain_helpers
node_process_lists -->|"validates with"| node_domain_utils
node_process_lists -->|"synchronizes"| node_gateway_lists
node_gateway_rules_create -->|"reads lists and upserts rules"| node_api_client
node_gateway_rules_delete -->|"reads and deletes rules"| node_api_client
node_gateway_lists_delete -->|"reads and deletes lists"| node_api_client
node_defragment -->|"reorganizes lists and rules"| node_api_client
node_api_client -->|"sends requests through"| node_request_helper
node_request_helper -->|"retries with"| node_http_utils
node_request_helper -->|"calls Gateway API"| node_cloudflare
node_process_lists -->|"notifies through"| node_http_utils
node_download -->|"downloads through"| node_http_utils
node_http_utils -->|"posts notifications"| node_webhook
node_gateway_rules_create -->|"notifies through"| node_http_utils
node_gateway_rules_delete -->|"notifies through"| node_http_utils
node_gateway_lists_delete -->|"notifies through"| node_http_utils
node_defragment -->|"notifies through"| node_http_utils

click node_download "https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/download_lists.js"
click node_download_helpers "https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/lib/utils.js"
click node_local_lists "https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/download_lists.js"
click node_process_lists "https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/cf_list_create.js"
click node_domain_helpers "https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/lib/helpers.js"
click node_domain_utils "https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/lib/utils.js"
click node_gateway_lists "https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/lib/api.js"
click node_gateway_rules_create "https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/cf_gateway_rule_create.js"
click node_gateway_rules_delete "https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/cf_gateway_rule_delete.js"
click node_gateway_lists_delete "https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/cf_list_delete.js"
click node_defragment "https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/cf_defragment.js"
click node_api_client "https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/lib/api.js"
click node_request_helper "https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/lib/helpers.js"
click node_http_utils "https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/lib/utils.js"

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_download,node_local_lists toneBlue
class node_process_lists,node_cloudflare toneAmber
class node_gateway_lists,node_gateway_rules_create,node_gateway_rules_delete,node_gateway_lists_delete,node_defragment,node_api_client,node_webhook toneMint
class node_download_helpers,node_domain_helpers,node_domain_utils,node_request_helper,node_http_utils toneRose
class node_operator,node_list_sources toneIndigo
```

## Components

### Filter inputs

- [Download lists](https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/download_lists.js): `download_lists.js`
- [Local filter files](https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/download_lists.js): `download_lists.js`

### Domain processing

- [Clean and reconcile domains](https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/cf_list_create.js): `cf_list_create.js`

### Gateway management

- [Gateway lists](https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/lib/api.js): `lib/api.js`
- [Create blocking rules](https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/cf_gateway_rule_create.js): `cf_gateway_rule_create.js`
- [Delete blocking rules](https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/cf_gateway_rule_delete.js): `cf_gateway_rule_delete.js`
- [Delete filter lists](https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/cf_list_delete.js): `cf_list_delete.js`
- [Defragment lists](https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/cf_defragment.js): `cf_defragment.js`
- [Gateway API operations](https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/lib/api.js): `lib/api.js`

### Shared runtime

- [File downloads](https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/lib/utils.js): `lib/utils.js`
- [Domain normalization](https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/lib/helpers.js): `lib/helpers.js`
- [Domain utilities](https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/lib/utils.js): `lib/utils.js`
- [Authenticated requests](https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/lib/helpers.js): `lib/helpers.js`
- [Retry and notifications](https://github.com/mrrfv/cloudflare-gateway-pihole-scripts/blob/main/lib/utils.js): `lib/utils.js`

### Other components

- **Operator**
- **List sources**
- **Cloudflare Gateway**
- **Notification webhook**

## Connections

- Operator → Download lists: runs (evidence: `README.md`)
- Operator → Clean and reconcile domains: runs (evidence: `README.md`)
- Operator → Create blocking rules: runs (evidence: `README.md`)
- Operator → Delete blocking rules: runs (evidence: `README.md`)
- Operator → Delete filter lists: runs (evidence: `README.md`)
- Operator → Defragment lists: runs
- List sources → Download lists: provides URLs (evidence: `download_lists.js`)
- Download lists → File downloads: downloads through (evidence: `download_lists.js`)
- File downloads → List sources: fetches files (evidence: `lib/utils.js`)
- Download lists → Local filter files: writes (evidence: `download_lists.js`)
- Local filter files → Clean and reconcile domains: reads (evidence: `cf_list_create.js`)
- Clean and reconcile domains → Domain normalization: normalizes with (evidence: `cf_list_create.js`)
- Clean and reconcile domains → Domain utilities: validates with (evidence: `cf_list_create.js`)
- Clean and reconcile domains → Gateway lists: synchronizes (evidence: `cf_list_create.js`)
- Create blocking rules → Gateway API operations: reads lists and upserts rules (evidence: `cf_gateway_rule_create.js`)
- Delete blocking rules → Gateway API operations: reads and deletes rules (evidence: `cf_gateway_rule_delete.js`)
- Delete filter lists → Gateway API operations: reads and deletes lists (evidence: `cf_list_delete.js`)
- Defragment lists → Gateway API operations: reorganizes lists and rules (evidence: `cf_defragment.js`)
- Gateway API operations → Authenticated requests: sends requests through (evidence: `lib/api.js`)
- Authenticated requests → Retry and notifications: retries with (evidence: `lib/helpers.js`)
- Authenticated requests → Cloudflare Gateway: calls Gateway API (evidence: `lib/helpers.js`)
- Clean and reconcile domains → Retry and notifications: notifies through (evidence: `cf_list_create.js`)
- Download lists → Retry and notifications: downloads through (evidence: `lib/utils.js`)
- Retry and notifications → Notification webhook: posts notifications (evidence: `lib/utils.js`)
- Create blocking rules → Retry and notifications: notifies through (evidence: `cf_gateway_rule_create.js`)
- Delete blocking rules → Retry and notifications: notifies through (evidence: `cf_gateway_rule_delete.js`)
- Delete filter lists → Retry and notifications: notifies through (evidence: `cf_list_delete.js`)
- Defragment lists → Retry and notifications: notifies through (evidence: `cf_defragment.js`)
