# mamali63/hachi-smart-dns architecture

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

- Interactive diagram: https://gitdiagram.com/mamali63/hachi-smart-dns
- Repository: https://github.com/mamali63/hachi-smart-dns
- Video tour (about a minute): https://gitdiagram.com/mamali63/hachi-smart-dns/video

## Overview

Hachi Smart DNS registers customer IPs, maintains a one-IP-per-customer whitelist, and uses DNS/SNI routing to steer selected game login and lobby traffic while leaving gameplay direct. The main workflow runs from customer code entry in the Android app through registration and whitelist generation to DNS routing; administrators manage users, domains, blocklists, and settings through the web panel or server-side CLI, with an hourly expiry sweep. Edges for unsampled panel and DNS behavior rely on README statements; no unsampled implementation was inspected.

Main entry points: [`server/admin_panel.py`](https://github.com/mamali63/hachi-smart-dns/blob/main/server/admin_panel.py) (Web Admin Panel), [`server/dns_admin.py`](https://github.com/mamali63/hachi-smart-dns/blob/main/server/dns_admin.py) (Admin CLI), [`config-samples/hachi-dns.conf`](https://github.com/mamali63/hachi-smart-dns/blob/main/config-samples/hachi-dns.conf) (Unbound DNS), [`server`](https://github.com/mamali63/hachi-smart-dns/tree/main/server) (IP Whitelist)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Customer App"]
  node_android_shell["Android Shell<br/>[MainActivity.java]"]
  node_app_ui["Code Entry UI<br/>[index.html]"]
end

subgraph group_registration["Registration Services"]
  node_registration_api["Registration API<br/>[reg_server.py]"]
  node_customer_records[("Customer Records")]
  node_whitelist[("IP Whitelist")]
  node_expiry_sweep["Expiry Sweep<br/>[dns_expire.py]"]
end

subgraph group_admin["Administration"]
  node_admin_panel["Web Admin Panel<br/>[admin_panel.py]"]
  node_admin_cli["Admin CLI<br/>[dns_admin.py]"]
  node_domains[("Game Domains<br/>[domains.json]")]
  node_domain_defaults["Default Domains"]
  node_blocklist[("Blocked Domains<br/>[blocked.json]")]
  node_dns_settings[("DNS Settings")]
end

subgraph group_dns["DNS Routing"]
  node_unbound["Unbound DNS<br/>[hachi-dns.conf]"]
  node_sni_config["SNI Rules<br/>[hachi-sni.conf]"]
  node_sniproxy["Sniproxy<br/>[sniproxy.conf]"]
end

node_customer(("Customer"))
node_administrator(("Administrator"))
node_game_services(("Game Services"))

node_customer -->|"opens app"| node_android_shell
node_android_shell -->|"loads UI"| node_app_ui
node_app_ui -->|"registers code"| node_registration_api
node_registration_api -->|"reads and updates"| node_customer_records
node_registration_api -->|"rebuilds"| node_whitelist
node_expiry_sweep -->|"reads"| node_customer_records
node_expiry_sweep -->|"rebuilds"| node_whitelist
node_administrator -->|"manages users"| node_admin_panel
node_administrator -->|"runs commands"| node_admin_cli
node_admin_panel -->|"manages"| node_domains
node_admin_panel -->|"resets from"| node_domain_defaults
node_admin_panel -->|"manages"| node_blocklist
node_admin_panel -->|"manages"| node_whitelist
node_admin_panel -->|"views and changes"| node_dns_settings
node_admin_panel -->|"rebuilds rules"| node_unbound
node_admin_panel -->|"reloads service"| node_sniproxy
node_admin_cli -->|"creates and updates"| node_customer_records
node_admin_cli -->|"rebuilds"| node_whitelist
node_admin_cli -->|"sets"| node_dns_settings
node_unbound -.->|"uses rules"| node_sni_config
node_unbound -->|"routes selected domains"| node_game_services
node_unbound -->|"forwards SNI traffic"| node_sniproxy

click node_android_shell "https://github.com/mamali63/hachi-smart-dns/blob/main/client/src/main/java/ir/hachitech/dns/MainActivity.java"
click node_app_ui "https://github.com/mamali63/hachi-smart-dns/blob/main/client/src/main/assets/www/index.html"
click node_registration_api "https://github.com/mamali63/hachi-smart-dns/blob/main/server/reg_server.py"
click node_customer_records "https://github.com/mamali63/hachi-smart-dns/tree/main/server"
click node_whitelist "https://github.com/mamali63/hachi-smart-dns/tree/main/server"
click node_expiry_sweep "https://github.com/mamali63/hachi-smart-dns/blob/main/server/dns_expire.py"
click node_admin_panel "https://github.com/mamali63/hachi-smart-dns/blob/main/server/admin_panel.py"
click node_admin_cli "https://github.com/mamali63/hachi-smart-dns/blob/main/server/dns_admin.py"
click node_domains "https://github.com/mamali63/hachi-smart-dns/blob/main/server/domains.json"
click node_domain_defaults "https://github.com/mamali63/hachi-smart-dns/blob/main/server/domains.default.json"
click node_blocklist "https://github.com/mamali63/hachi-smart-dns/blob/main/server/blocked.json"
click node_dns_settings "https://github.com/mamali63/hachi-smart-dns/tree/main/server"
click node_unbound "https://github.com/mamali63/hachi-smart-dns/blob/main/config-samples/hachi-dns.conf"
click node_sni_config "https://github.com/mamali63/hachi-smart-dns/blob/main/config-samples/hachi-sni.conf"
click node_sniproxy "https://github.com/mamali63/hachi-smart-dns/blob/main/config-samples/sniproxy.conf"

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_android_shell,node_app_ui toneBlue
class node_registration_api,node_customer_records,node_whitelist,node_expiry_sweep toneAmber
class node_admin_panel,node_admin_cli,node_domains,node_domain_defaults,node_blocklist,node_dns_settings toneMint
class node_unbound,node_sni_config,node_sniproxy toneRose
class node_customer,node_administrator,node_game_services toneIndigo
```

## Components

### Customer App

- [Android Shell](https://github.com/mamali63/hachi-smart-dns/blob/main/client/src/main/java/ir/hachitech/dns/MainActivity.java): `client/src/main/java/ir/hachitech/dns/MainActivity.java`
- [Code Entry UI](https://github.com/mamali63/hachi-smart-dns/blob/main/client/src/main/assets/www/index.html): `client/src/main/assets/www/index.html`

### Registration Services

- [Registration API](https://github.com/mamali63/hachi-smart-dns/blob/main/server/reg_server.py): `server/reg_server.py`
- [Customer Records](https://github.com/mamali63/hachi-smart-dns/tree/main/server): `server`
- [IP Whitelist](https://github.com/mamali63/hachi-smart-dns/tree/main/server): `server`
- [Expiry Sweep](https://github.com/mamali63/hachi-smart-dns/blob/main/server/dns_expire.py): `server/dns_expire.py`

### Administration

- [Web Admin Panel](https://github.com/mamali63/hachi-smart-dns/blob/main/server/admin_panel.py): `server/admin_panel.py`
- [Admin CLI](https://github.com/mamali63/hachi-smart-dns/blob/main/server/dns_admin.py): `server/dns_admin.py`
- [Game Domains](https://github.com/mamali63/hachi-smart-dns/blob/main/server/domains.json): `server/domains.json`
- [Default Domains](https://github.com/mamali63/hachi-smart-dns/blob/main/server/domains.default.json): `server/domains.default.json`
- [Blocked Domains](https://github.com/mamali63/hachi-smart-dns/blob/main/server/blocked.json): `server/blocked.json`
- [DNS Settings](https://github.com/mamali63/hachi-smart-dns/tree/main/server): `server`

### DNS Routing

- [Unbound DNS](https://github.com/mamali63/hachi-smart-dns/blob/main/config-samples/hachi-dns.conf): `config-samples/hachi-dns.conf`
- [SNI Rules](https://github.com/mamali63/hachi-smart-dns/blob/main/config-samples/hachi-sni.conf): `config-samples/hachi-sni.conf`
- [Sniproxy](https://github.com/mamali63/hachi-smart-dns/blob/main/config-samples/sniproxy.conf): `config-samples/sniproxy.conf`

### Other components

- **Customer**
- **Administrator**
- **Game Services**

## Connections

- Customer → Android Shell: opens app (evidence: `README.md`)
- Android Shell → Code Entry UI: loads UI (evidence: `client/src/main/java/ir/hachitech/dns/MainActivity.java`)
- Code Entry UI → Registration API: registers code (evidence: `README.md`)
- Registration API → Customer Records: reads and updates (evidence: `server/reg_server.py`)
- Registration API → IP Whitelist: rebuilds (evidence: `server/reg_server.py`)
- Expiry Sweep → Customer Records: reads (evidence: `server/dns_expire.py`)
- Expiry Sweep → IP Whitelist: rebuilds (evidence: `server/dns_expire.py`)
- Administrator → Web Admin Panel: manages users (evidence: `README.md`)
- Administrator → Admin CLI: runs commands (evidence: `README.md`)
- Web Admin Panel → Game Domains: manages (evidence: `README.md`)
- Web Admin Panel → Default Domains: resets from (evidence: `README.md`)
- Web Admin Panel → Blocked Domains: manages (evidence: `README.md`)
- Web Admin Panel → IP Whitelist: manages (evidence: `README.md`)
- Web Admin Panel → DNS Settings: views and changes (evidence: `README.md`)
- Web Admin Panel → Unbound DNS: rebuilds rules (evidence: `README.md`)
- Web Admin Panel → Sniproxy: reloads service (evidence: `README.md`)
- Admin CLI → Customer Records: creates and updates (evidence: `server/dns_admin.py`)
- Admin CLI → IP Whitelist: rebuilds (evidence: `server/dns_admin.py`)
- Admin CLI → DNS Settings: sets (evidence: `server/dns_admin.py`)
- Unbound DNS → SNI Rules: uses rules (evidence: `README.md`)
- Unbound DNS → Game Services: routes selected domains (evidence: `README.md`)
- Unbound DNS → Sniproxy: forwards SNI traffic (evidence: `README.md`)