@@ -8,8 +8,8 @@ This document provides a comprehensive overview of the Pi-hole architecture insp
88- [ Level 2: Container Diagram] ( #level-2-container-diagram )
99- [ Level 3: Component Diagram] ( #level-3-component-diagram )
1010- [ Additional Diagrams] ( #additional-diagrams )
11- - [ DNS Query Flow] ( #dns-query-flow )
12- - [ Blocklist Update Process] ( #blocklist-update-process )
11+ - [ DNS Query Flow] ( #dns-query-flow )
12+ - [ Blocklist Update Process] ( #blocklist-update-process )
1313
1414## Level 1: System Context
1515
@@ -47,12 +47,19 @@ graph TB
4747```
4848
4949The System Context diagram shows:
50+
5051- ** Network Users** : People using devices on the network protected by Pi-hole
52+
5153- ** Pi-hole Administrator** : Person who configures and maintains the Pi-hole system
54+
5255- ** Client Devices** : Computers, phones, smart TVs, and other devices on the network
56+
5357- ** Network Router** : Directs network traffic and is configured to use Pi-hole as the DNS server
58+
5459- ** Upstream DNS Servers** : External DNS servers that Pi-hole forwards allowed queries to
60+
5561- ** Ad List Providers** : Sources of domain blocklists that Pi-hole downloads
62+
5663- ** Internet** : The broader internet that devices access through Pi-hole's filtering
5764
5865## Level 2: Container Diagram
@@ -114,11 +121,17 @@ flowchart TB
114121```
115122
116123The Container diagram shows:
124+
117125- ** FTL DNS Service** : The core DNS service that processes queries and blocks ads
126+
118127- ** Web Admin Interface** : The web-based dashboard for managing Pi-hole
128+
119129- ** Command Line Interface** : The terminal-based interface for administration
130+
120131- ** Gravity Updater** : The component that downloads and processes blocklists
132+
121133- ** Databases** : The Gravity DB (for blocklists) and FTL DB (for statistics)
134+
122135- ** Configuration Files** : Settings that control Pi-hole's behavior
123136
124137## Level 3: Component Diagram
@@ -176,12 +189,19 @@ flowchart TB
176189```
177190
178191The Component diagram shows:
192+
179193- ** DNS Resolver** : Handles incoming DNS queries and returns responses
194+
180195- ** Query Analyzer** : Processes queries to determine if they should be blocked
196+
181197- ** Blocking Engine** : Implements the blocking logic based on blocklists
198+
182199- ** Cache Manager** : Manages the DNS cache for improved performance
200+
183201- ** API Server** : Provides an HTTP API for the Web Admin Interface
202+
184203- ** Telnet Server** : Provides a telnet interface for direct queries
204+
185205- ** Statistics Collector** : Gathers and stores statistics about DNS queries
186206
187207
@@ -226,6 +246,7 @@ sequenceDiagram
226246```
227247
228248This sequence diagram shows:
249+
2292501 . A client device sends a DNS query to the router
2302512 . The router forwards the query to Pi-hole's FTL service
2312523 . FTL checks if the domain is in its cache
@@ -277,6 +298,7 @@ flowchart TD
277298```
278299
279300This flowchart shows:
301+
2803021 . The process starts with checking internet connectivity
2813032 . Blocklists are fetched from various sources
2823043 . Lists are processed, deduplicated, and filtered
0 commit comments