# greepar/cfspeedtest architecture

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

- Interactive diagram: https://gitdiagram.com/greepar/cfspeedtest
- Repository: https://github.com/greepar/cfspeedtest

## Overview

CfSpeedtest coordinates recurring, carrier-specific Cloudflare IP tests: an operator configures pools and test settings in the WebUI; the server assigns tasks, clients measure candidate IPs and report Top-N results, and the server records rounds and may update DNS. The server also exposes client management, history, notifications, authentication, and update controls. The tree and README establish these capabilities; sampled excerpts confirm several service interactions, but not every route-to-service wiring, so uncertain links are omitted.

Main entry points: [`src/CfSpeedtest.Web/src/App.tsx`](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Web/src/App.tsx) (Admin UI), [`src/CfSpeedtest.Server/Program.cs`](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Server/Program.cs) (HTTP server), [`src/CfSpeedtest.Client/Program.cs`](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Client/Program.cs) (Test agent), [`src/CfSpeedtest.Server/Services/RoundCoordinatorService.cs`](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Server/Services/RoundCoordinatorService.cs) (Round coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Test client"]
  node_client_agent["Test agent<br/>[Program.cs]"]
end

subgraph group_server["Server runtime"]
  node_server["HTTP server<br/>[Program.cs]"]
  node_rounds["Round coordinator"]
  node_pool["IP pool service<br/>[IpPoolService.cs]"]
  node_store["Persistent state<br/>[DataStore.cs]"]
  node_hub["Client WebSocket hub<br/>[ClientWsHub.cs]"]
  node_dns["DNS updater"]
  node_auth["Web authentication"]
  node_webhooks["Webhook service"]
  node_updater["Server updater"]
  node_shared["Shared contracts<br/>[Models.cs]"]
end

subgraph group_web["Web management"]
  node_web_app["Admin UI<br/>[App.tsx]"]
  node_overview["Overview<br/>[Overview.tsx]"]
  node_history["Test history<br/>[HistoryPage.tsx]"]
  node_clients["Client admin<br/>[ClientsPage.tsx]"]
  node_ip_page["IP pools<br/>[IpPoolPage.tsx]"]
  node_dns_page["DNS settings<br/>[DnsPage.tsx]"]
  node_config_page["Server config<br/>[ConfigPage.tsx]"]
  node_notify_page["Notifications"]
  node_web_api["API client<br/>[api.ts]"]
end

subgraph group_integrations["External systems"]
  node_target(("Test endpoints"))
  node_fetch_sources(("IP source APIs"))
  node_doh(("DoH resolver"))
  node_dns_provider(("Huawei DNS"))
  node_webhook_target(("Webhook receiver"))
  node_release_host(("GitHub Releases"))
end

node_operator(("Operator"))

node_operator -->|"manages"| node_web_app
node_web_app -->|"requests"| node_web_api
node_web_api -->|"calls API"| node_server
node_server -->|"authenticates"| node_auth
node_server -->|"reads/writes"| node_store
node_server -->|"dispatches"| node_hub
node_server -->|"coordinates"| node_rounds
node_rounds -->|"refreshes pool"| node_pool
node_rounds -->|"updates records"| node_dns
node_rounds -->|"stores results"| node_store
node_pool -->|"reads/writes"| node_store
node_pool -.->|"fetches addresses"| node_fetch_sources
node_pool -.->|"resolves A records"| node_doh
node_dns -.->|"updates DNS"| node_dns_provider
node_webhooks -.->|"sends notices"| node_webhook_target
node_server -->|"notifies"| node_webhooks
node_server -->|"checks/installs"| node_updater
node_updater -.->|"fetches release"| node_release_host
node_client_agent -->|"registers/reports"| node_server
node_client_agent -->|"connects"| node_hub
node_hub -->|"sends tasks"| node_client_agent
node_client_agent -.->|"tests IPs"| node_target
node_web_app -->|"shows"| node_overview
node_web_app -->|"shows"| node_history
node_web_app -->|"shows"| node_clients
node_web_app -->|"shows"| node_ip_page
node_web_app -->|"shows"| node_dns_page
node_web_app -->|"shows"| node_config_page
node_web_app -->|"shows"| node_notify_page
node_shared -->|"defines contracts"| node_server
node_shared -->|"defines contracts"| node_client_agent

click node_client_agent "https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Client/Program.cs"
click node_web_app "https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Web/src/App.tsx"
click node_overview "https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Web/src/pages/Overview.tsx"
click node_history "https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Web/src/pages/HistoryPage.tsx"
click node_clients "https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Web/src/pages/ClientsPage.tsx"
click node_ip_page "https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Web/src/pages/IpPoolPage.tsx"
click node_dns_page "https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Web/src/pages/DnsPage.tsx"
click node_config_page "https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Web/src/pages/ConfigPage.tsx"
click node_notify_page "https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Web/src/pages/NotificationsPage.tsx"
click node_web_api "https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Web/src/lib/api.ts"
click node_server "https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Server/Program.cs"
click node_rounds "https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Server/Services/RoundCoordinatorService.cs"
click node_pool "https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Server/Services/IpPoolService.cs"
click node_store "https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Server/Services/DataStore.cs"
click node_hub "https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Server/Services/ClientWsHub.cs"
click node_dns "https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Server/Services/DnsUpdateService.cs"
click node_auth "https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Server/Services/WebUiAuthService.cs"
click node_webhooks "https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Server/Services/WebhookNotificationService.cs"
click node_updater "https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Server/Services/ServerUpdateService.cs"
click node_shared "https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Shared/Models.cs"

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_client_agent toneBlue
class node_server,node_rounds,node_pool,node_store,node_hub,node_dns,node_auth,node_webhooks,node_updater,node_shared toneAmber
class node_web_app,node_overview,node_history,node_clients,node_ip_page,node_dns_page,node_config_page,node_notify_page,node_web_api toneMint
class node_target,node_fetch_sources,node_doh,node_dns_provider,node_webhook_target,node_release_host toneRose
class node_operator toneIndigo
```

## Components

### Test client

- [Test agent](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Client/Program.cs): `src/CfSpeedtest.Client/Program.cs`

### Server runtime

- [HTTP server](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Server/Program.cs): `src/CfSpeedtest.Server/Program.cs`
- [Round coordinator](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Server/Services/RoundCoordinatorService.cs): `src/CfSpeedtest.Server/Services/RoundCoordinatorService.cs`
- [IP pool service](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Server/Services/IpPoolService.cs): `src/CfSpeedtest.Server/Services/IpPoolService.cs`
- [Persistent state](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Server/Services/DataStore.cs): `src/CfSpeedtest.Server/Services/DataStore.cs`
- [Client WebSocket hub](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Server/Services/ClientWsHub.cs): `src/CfSpeedtest.Server/Services/ClientWsHub.cs`
- [DNS updater](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Server/Services/DnsUpdateService.cs): `src/CfSpeedtest.Server/Services/DnsUpdateService.cs`
- [Web authentication](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Server/Services/WebUiAuthService.cs): `src/CfSpeedtest.Server/Services/WebUiAuthService.cs`
- [Webhook service](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Server/Services/WebhookNotificationService.cs): `src/CfSpeedtest.Server/Services/WebhookNotificationService.cs`
- [Server updater](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Server/Services/ServerUpdateService.cs): `src/CfSpeedtest.Server/Services/ServerUpdateService.cs`
- [Shared contracts](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Shared/Models.cs): `src/CfSpeedtest.Shared/Models.cs`

### Web management

- [Admin UI](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Web/src/App.tsx): `src/CfSpeedtest.Web/src/App.tsx`
- [Overview](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Web/src/pages/Overview.tsx): `src/CfSpeedtest.Web/src/pages/Overview.tsx`
- [Test history](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Web/src/pages/HistoryPage.tsx): `src/CfSpeedtest.Web/src/pages/HistoryPage.tsx`
- [Client admin](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Web/src/pages/ClientsPage.tsx): `src/CfSpeedtest.Web/src/pages/ClientsPage.tsx`
- [IP pools](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Web/src/pages/IpPoolPage.tsx): `src/CfSpeedtest.Web/src/pages/IpPoolPage.tsx`
- [DNS settings](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Web/src/pages/DnsPage.tsx): `src/CfSpeedtest.Web/src/pages/DnsPage.tsx`
- [Server config](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Web/src/pages/ConfigPage.tsx): `src/CfSpeedtest.Web/src/pages/ConfigPage.tsx`
- [Notifications](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Web/src/pages/NotificationsPage.tsx): `src/CfSpeedtest.Web/src/pages/NotificationsPage.tsx`
- [API client](https://github.com/greepar/cfspeedtest/blob/main/src/CfSpeedtest.Web/src/lib/api.ts): `src/CfSpeedtest.Web/src/lib/api.ts`

### External systems

- **Test endpoints**
- **IP source APIs**
- **DoH resolver**
- **Huawei DNS**
- **Webhook receiver**
- **GitHub Releases**

### Other components

- **Operator**

## Connections

- Operator → Admin UI: manages
- Admin UI → API client: requests
- API client → HTTP server: calls API
- HTTP server → Web authentication: authenticates
- HTTP server → Persistent state: reads/writes
- HTTP server → Client WebSocket hub: dispatches
- HTTP server → Round coordinator: coordinates
- Round coordinator → IP pool service: refreshes pool
- Round coordinator → DNS updater: updates records
- Round coordinator → Persistent state: stores results
- IP pool service → Persistent state: reads/writes
- IP pool service → IP source APIs: fetches addresses
- IP pool service → DoH resolver: resolves A records
- DNS updater → Huawei DNS: updates DNS
- Webhook service → Webhook receiver: sends notices
- HTTP server → Webhook service: notifies
- HTTP server → Server updater: checks/installs
- Server updater → GitHub Releases: fetches release
- Test agent → HTTP server: registers/reports
- Test agent → Client WebSocket hub: connects
- Client WebSocket hub → Test agent: sends tasks
- Test agent → Test endpoints: tests IPs
- Admin UI → Overview: shows
- Admin UI → Test history: shows
- Admin UI → Client admin: shows
- Admin UI → IP pools: shows
- Admin UI → DNS settings: shows
- Admin UI → Server config: shows
- Admin UI → Notifications: shows
- Shared contracts → HTTP server: defines contracts
- Shared contracts → Test agent: defines contracts
