# adguardteam/adguardhome architecture

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

- Interactive diagram: https://gitdiagram.com/adguardteam/adguardhome
- Repository: https://github.com/adguardteam/adguardhome

## Overview

AdGuard Home is a self-hosted DNS server for network-wide ad and tracker blocking. The principal workflow is that devices send DNS queries to the server, which applies filtering and returns a response; administrators configure policy and inspect activity through the web interface or REST API. Major documented capabilities include custom filtering, client management, DHCP, encrypted DNS, and HTTPS administration. The tree and excerpts show several UI and storage details, but not the full DNS request path, so uncertain backend connections are omitted.

Main entry points: [`internal/home/clientshttp.go`](https://github.com/adguardteam/adguardhome/blob/master/internal/home/clientshttp.go) (Client API), [`internal/dnsforward/requesthandler.go`](https://github.com/adguardteam/adguardhome/blob/master/internal/dnsforward/requesthandler.go) (DNS server), [`internal/home/service.go`](https://github.com/adguardteam/adguardhome/blob/master/internal/home/service.go) (Web service), [`client/src/components/Logs/index.tsx`](https://github.com/adguardteam/adguardhome/blob/master/client/src/components/Logs/index.tsx) (Query log view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dns["DNS protection"]
  node_dns_service["DNS server<br/>[requesthandler.go]"]
  node_filter_engine["Filtering rules<br/>[engine.go]"]
  node_rewrites[("DNS rewrites<br/>[storage.go]")]
  node_upstream["DNS upstreams<br/>[upstreammanager.go]"]
end

subgraph group_admin["Administration API"]
  node_web_service["Web service<br/>[service.go]"]
  node_client_api["Client API<br/>[clientshttp.go]"]
end

subgraph group_web["Web interface"]
  node_web_app["Admin interface<br/>[index.tsx]"]
  node_api_client["API client<br/>[Api.ts]"]
  node_query_logs_ui["Query log view<br/>[index.tsx]"]
  node_query_actions["Query log actions<br/>[queryLogs.ts]"]
  node_dashboard["Dashboard<br/>[Dashboard.tsx]"]
  node_client_ui["Client settings<br/>[Clients.tsx]"]
  node_filters_ui["Filter controls"]
  node_dhcp_ui["DHCP settings<br/>[index.tsx]"]
  node_settings_ui["DNS settings<br/>[index.tsx]"]
end

subgraph group_state["State and services"]
  node_clients[("Client registry<br/>[storage.go]")]
  node_dhcp["DHCP service<br/>[server.go]"]
  node_query_log[("Query log<br/>[querylog.go]")]
  node_log_files["Log files<br/>[querylogfile.go]"]
  node_tls_manager["TLS certificates<br/>[defaultmanager.go]"]
  node_session_store[("User sessions<br/>[sessionstorage.go]")]
end

node_devices(("Network devices"))
node_admin_actor(("Administrator"))
node_ui_actor(("Web administrator"))

node_devices -->|"send DNS queries"| node_dns_service
node_dns_service -.->|"applies rules"| node_filter_engine
node_dns_service -.->|"checks rewrites"| node_rewrites
node_dns_service -.->|"uses upstreams"| node_upstream
node_admin_actor -->|"configures server"| node_web_service
node_web_service -.->|"serves API"| node_client_api
node_client_api -->|"reads and updates"| node_clients
node_ui_actor -.->|"uses interface"| node_web_app
node_web_app -.->|"uses API"| node_api_client
node_query_logs_ui -->|"dispatches actions"| node_query_actions
node_query_actions -->|"requests log data"| node_api_client
node_query_logs_ui -.->|"reviews activity"| node_dashboard
node_client_ui -.->|"manages clients"| node_client_api
node_filters_ui -.->|"configures filtering"| node_client_api
node_dhcp_ui -.->|"configures DHCP"| node_client_api
node_settings_ui -.->|"configures DNS"| node_client_api
node_query_log -.->|"persists entries"| node_log_files
node_tls_manager -.->|"supports HTTPS"| node_web_service
node_session_store -.->|"stores sessions"| node_web_service

click node_dns_service "https://github.com/adguardteam/adguardhome/blob/master/internal/dnsforward/requesthandler.go"
click node_filter_engine "https://github.com/adguardteam/adguardhome/blob/master/internal/filtering/rulelist/engine.go"
click node_rewrites "https://github.com/adguardteam/adguardhome/blob/master/internal/filtering/rewrite/storage.go"
click node_upstream "https://github.com/adguardteam/adguardhome/blob/master/internal/client/upstreammanager.go"
click node_web_service "https://github.com/adguardteam/adguardhome/blob/master/internal/home/service.go"
click node_client_api "https://github.com/adguardteam/adguardhome/blob/master/internal/home/clientshttp.go"
click node_clients "https://github.com/adguardteam/adguardhome/blob/master/internal/client/storage.go"
click node_dhcp "https://github.com/adguardteam/adguardhome/blob/master/internal/dhcpsvc/server.go"
click node_query_log "https://github.com/adguardteam/adguardhome/blob/master/internal/querylog/querylog.go"
click node_log_files "https://github.com/adguardteam/adguardhome/blob/master/internal/querylog/querylogfile.go"
click node_tls_manager "https://github.com/adguardteam/adguardhome/blob/master/internal/aghtls/defaultmanager.go"
click node_session_store "https://github.com/adguardteam/adguardhome/blob/master/internal/aghuser/sessionstorage.go"
click node_web_app "https://github.com/adguardteam/adguardhome/blob/master/client_v2/src/components/App/index.tsx"
click node_api_client "https://github.com/adguardteam/adguardhome/blob/master/client/src/api/Api.ts"
click node_query_logs_ui "https://github.com/adguardteam/adguardhome/blob/master/client/src/components/Logs/index.tsx"
click node_query_actions "https://github.com/adguardteam/adguardhome/blob/master/client/src/actions/queryLogs.ts"
click node_dashboard "https://github.com/adguardteam/adguardhome/blob/master/client_v2/src/components/Dashboard/Dashboard.tsx"
click node_client_ui "https://github.com/adguardteam/adguardhome/blob/master/client_v2/src/components/Clients/Clients.tsx"
click node_dhcp_ui "https://github.com/adguardteam/adguardhome/blob/master/client/src/components/Settings/Dhcp/index.tsx"
click node_settings_ui "https://github.com/adguardteam/adguardhome/blob/master/client/src/components/Settings/Dns/index.tsx"

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_dns_service,node_filter_engine,node_rewrites,node_upstream toneBlue
class node_web_service,node_client_api toneAmber
class node_web_app,node_api_client,node_query_logs_ui,node_query_actions,node_dashboard,node_client_ui,node_filters_ui,node_dhcp_ui,node_settings_ui toneMint
class node_clients,node_dhcp,node_query_log,node_log_files,node_tls_manager,node_session_store toneRose
class node_devices,node_admin_actor,node_ui_actor toneIndigo
```

## Components

### DNS protection

- [DNS server](https://github.com/adguardteam/adguardhome/blob/master/internal/dnsforward/requesthandler.go): `internal/dnsforward/requesthandler.go`
- [Filtering rules](https://github.com/adguardteam/adguardhome/blob/master/internal/filtering/rulelist/engine.go): `internal/filtering/rulelist/engine.go`
- [DNS rewrites](https://github.com/adguardteam/adguardhome/blob/master/internal/filtering/rewrite/storage.go): `internal/filtering/rewrite/storage.go`
- [DNS upstreams](https://github.com/adguardteam/adguardhome/blob/master/internal/client/upstreammanager.go): `internal/client/upstreammanager.go`

### Administration API

- [Web service](https://github.com/adguardteam/adguardhome/blob/master/internal/home/service.go): `internal/home/service.go`
- [Client API](https://github.com/adguardteam/adguardhome/blob/master/internal/home/clientshttp.go): `internal/home/clientshttp.go`

### Web interface

- [Admin interface](https://github.com/adguardteam/adguardhome/blob/master/client_v2/src/components/App/index.tsx): `client_v2/src/components/App/index.tsx`
- [API client](https://github.com/adguardteam/adguardhome/blob/master/client/src/api/Api.ts): `client/src/api/Api.ts`
- [Query log view](https://github.com/adguardteam/adguardhome/blob/master/client/src/components/Logs/index.tsx): `client/src/components/Logs/index.tsx`
- [Query log actions](https://github.com/adguardteam/adguardhome/blob/master/client/src/actions/queryLogs.ts): `client/src/actions/queryLogs.ts`
- [Dashboard](https://github.com/adguardteam/adguardhome/blob/master/client_v2/src/components/Dashboard/Dashboard.tsx): `client_v2/src/components/Dashboard/Dashboard.tsx`
- [Client settings](https://github.com/adguardteam/adguardhome/blob/master/client_v2/src/components/Clients/Clients.tsx): `client_v2/src/components/Clients/Clients.tsx`
- **Filter controls**
- [DHCP settings](https://github.com/adguardteam/adguardhome/blob/master/client/src/components/Settings/Dhcp/index.tsx): `client/src/components/Settings/Dhcp/index.tsx`
- [DNS settings](https://github.com/adguardteam/adguardhome/blob/master/client/src/components/Settings/Dns/index.tsx): `client/src/components/Settings/Dns/index.tsx`

### State and services

- [Client registry](https://github.com/adguardteam/adguardhome/blob/master/internal/client/storage.go): `internal/client/storage.go`
- [DHCP service](https://github.com/adguardteam/adguardhome/blob/master/internal/dhcpsvc/server.go): `internal/dhcpsvc/server.go`
- [Query log](https://github.com/adguardteam/adguardhome/blob/master/internal/querylog/querylog.go): `internal/querylog/querylog.go`
- [Log files](https://github.com/adguardteam/adguardhome/blob/master/internal/querylog/querylogfile.go): `internal/querylog/querylogfile.go`
- [TLS certificates](https://github.com/adguardteam/adguardhome/blob/master/internal/aghtls/defaultmanager.go): `internal/aghtls/defaultmanager.go`
- [User sessions](https://github.com/adguardteam/adguardhome/blob/master/internal/aghuser/sessionstorage.go): `internal/aghuser/sessionstorage.go`

### Other components

- **Network devices**
- **Administrator**
- **Web administrator**

## Connections

- Network devices → DNS server: send DNS queries (evidence: `README.md`)
- DNS server → Filtering rules: applies rules
- DNS server → DNS rewrites: checks rewrites
- DNS server → DNS upstreams: uses upstreams
- Administrator → Web service: configures server (evidence: `README.md`)
- Web service → Client API: serves API
- Client API → Client registry: reads and updates (evidence: `internal/home/clientshttp.go`)
- Web administrator → Admin interface: uses interface
- Admin interface → API client: uses API
- Query log view → Query log actions: dispatches actions (evidence: `client/src/components/Logs/index.tsx`)
- Query log actions → API client: requests log data (evidence: `client/src/actions/queryLogs.ts`)
- Query log view → Dashboard: reviews activity
- Client settings → Client API: manages clients
- Filter controls → Client API: configures filtering
- DHCP settings → Client API: configures DHCP
- DNS settings → Client API: configures DNS
- Query log → Log files: persists entries
- TLS certificates → Web service: supports HTTPS
- User sessions → Web service: stores sessions
