@@ -8,8 +8,8 @@ This document provides a comprehensive overview of the Pi-hole architecture insp
8
8
- [ Level 2: Container Diagram] ( #level-2-container-diagram )
9
9
- [ Level 3: Component Diagram] ( #level-3-component-diagram )
10
10
- [ 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 )
13
13
14
14
## Level 1: System Context
15
15
@@ -47,12 +47,19 @@ graph TB
47
47
```
48
48
49
49
The System Context diagram shows:
50
+
50
51
- ** Network Users** : People using devices on the network protected by Pi-hole
52
+
51
53
- ** Pi-hole Administrator** : Person who configures and maintains the Pi-hole system
54
+
52
55
- ** Client Devices** : Computers, phones, smart TVs, and other devices on the network
56
+
53
57
- ** Network Router** : Directs network traffic and is configured to use Pi-hole as the DNS server
58
+
54
59
- ** Upstream DNS Servers** : External DNS servers that Pi-hole forwards allowed queries to
60
+
55
61
- ** Ad List Providers** : Sources of domain blocklists that Pi-hole downloads
62
+
56
63
- ** Internet** : The broader internet that devices access through Pi-hole's filtering
57
64
58
65
## Level 2: Container Diagram
@@ -114,11 +121,17 @@ flowchart TB
114
121
```
115
122
116
123
The Container diagram shows:
124
+
117
125
- ** FTL DNS Service** : The core DNS service that processes queries and blocks ads
126
+
118
127
- ** Web Admin Interface** : The web-based dashboard for managing Pi-hole
128
+
119
129
- ** Command Line Interface** : The terminal-based interface for administration
130
+
120
131
- ** Gravity Updater** : The component that downloads and processes blocklists
132
+
121
133
- ** Databases** : The Gravity DB (for blocklists) and FTL DB (for statistics)
134
+
122
135
- ** Configuration Files** : Settings that control Pi-hole's behavior
123
136
124
137
## Level 3: Component Diagram
@@ -176,12 +189,19 @@ flowchart TB
176
189
```
177
190
178
191
The Component diagram shows:
192
+
179
193
- ** DNS Resolver** : Handles incoming DNS queries and returns responses
194
+
180
195
- ** Query Analyzer** : Processes queries to determine if they should be blocked
196
+
181
197
- ** Blocking Engine** : Implements the blocking logic based on blocklists
198
+
182
199
- ** Cache Manager** : Manages the DNS cache for improved performance
200
+
183
201
- ** API Server** : Provides an HTTP API for the Web Admin Interface
202
+
184
203
- ** Telnet Server** : Provides a telnet interface for direct queries
204
+
185
205
- ** Statistics Collector** : Gathers and stores statistics about DNS queries
186
206
187
207
@@ -226,6 +246,7 @@ sequenceDiagram
226
246
```
227
247
228
248
This sequence diagram shows:
249
+
229
250
1 . A client device sends a DNS query to the router
230
251
2 . The router forwards the query to Pi-hole's FTL service
231
252
3 . FTL checks if the domain is in its cache
@@ -277,6 +298,7 @@ flowchart TD
277
298
```
278
299
279
300
This flowchart shows:
301
+
280
302
1 . The process starts with checking internet connectivity
281
303
2 . Blocklists are fetched from various sources
282
304
3 . Lists are processed, deduplicated, and filtered
0 commit comments