# itsyebekhe/nahan architecture

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

- Interactive diagram: https://gitdiagram.com/itsyebekhe/nahan
- Repository: https://github.com/itsyebekhe/nahan

## Overview

1. **What this repository is**
   - Nahan is a single-edge application built for **Cloudflare Workers**. It combines a reverse-proxy/gateway, a management dashboard, and subscription/config generation in one deployable worker.
   - The architecture is intentionally serverless: no VPS, no long-running process, and persistent state is pushed into **Cloudflare D1**.

2. **Primary runtime boundary**
   - The core runtime is the **`_worker.js`** file, which is the actual Cloudflare Worker entrypoint and appears to contain the full application logic.
   - `wrangler.toml` defines the Worker deployment and bindings, especially the D1 database binding expected as **`IOT_DB`**.

3. **Persistent state layer**
   - Configuration is stored in **D1 SQLite**, not in memory or KV, so settings survive code redeploys.
   - The README indicates a `kv_store` table inside D1 for values such as `masterKey`, API route, and other dashboard settings.
   - This is the main state boundary: the Worker reads/writes configuration from D1, while request handling remains stateless between invocations.

4. **Public request surface**
   - The Worker exposes multiple HTTP entrypoints:
     - a **camouflage root** that returns a legitimate-looking site instead of the admin UI,
     - a **dashboard route** at `/<api-route>/dash`,
     - a **subscription endpoint** at `/<api-route>/sub`,
     - and likely supporting routes for sync/auth/update actions under the same API prefix.
   - The API route is configurable, so the dashboard can move away from the default `/sync` path.

5. **Gateway/proxy plane**
   - Nahan is not just a dashboard; it also acts as a **reverse proxy / gateway** for **VLESS** and **Trojan**-style client configs.
   - The “Alpha / Beta / Both” mode in the UI maps to protocol selection in generated outbound configs.
   - The proxy behavior is designed to obscure the real service behind normal-looking traffic, including a **kill switch** that can pause forwarding globally.

6. **Admin UI plane**
   - The repo includes **`dashboard.html`**, **`index.html`**, and **`subscription.html`**, which strongly suggests the UI is self-contained and served by the Worker rather than by a separate frontend stack.
   - The dashboard is multilingual and interactive, with dark/light mode and sections for endpoints, metrics, system settings, advanced network settings, and activity logs.
   - `tailwindcss.js` suggests client-side styling support for the embedded UI, likely bundled or inlined rather than using a separate frontend build pipeline.

7. **Subscription/config generation**
   - The Worker generates client subscription output for tools like v2rayN, Hiddify, Shadowrocket, and Nekoray.
   - The included `singbox.json` and `vtwo.json` files are likely config templates or sample outputs used for protocol-specific generation.
   - QR code generation is part of the dashboard flow, so the Worker returns both human-readable UI and machine-consumable config payloads.

8. **Multi-user and fan-out behavior**
   - The system supports **multi-user profiles** via `uuid:Name` entries.
   - Each profile gets its own subscription view, and the worker can fan out one logical profile across multiple clean IP targets.
   - This means the Worker acts as a config assembler: it composes a per-user/per-node subscription from stored profiles plus runtime network data.

9. **Clean IP and NAT64 handling**
   - A key advanced feature is the **clean IP multiplexer**, where a list of clean IPs or hostnames is stored in settings and then expanded into multiple generated endpoints.
   - NAT64 support is part of the config generation path, meaning the worker may transform or augment addressing when producing client configs.
   - These are configuration-time transformations rather than separate services.

10. **External integrations**
   - **Telegram Bot** integration is a control plane extension: it can send alerts, report status, and trigger actions like the kill switch.
   - **Cloudflare Analytics** integration is optional and used to monitor request usage against Cloudflare limits.
   - These integrations are outbound-only from the Worker and do not introduce separate backend components.

11. **Operational workflow**
   - The system is configured by logging into the dashboard with a master key, then updating settings that are persisted to D1.
   - Changes are applied immediately via Worker request handling; there is no separate deploy step for config changes.
   - If the API route changes, the operational boundary changes too: the dashboard URL moves, but the stored state remains intact.

12. **Repository structure and support files**
   - `README.md`, `HELP.md`, and the Persian equivalents document the same single-service architecture for different audiences.
   - `.github/ISSUE_TEMPLATE` and `CHANGELOG.md` are support/maintenance assets, not runtime components.
   - The `version` file likely acts as a release marker for update checks or display in the UI.

13. **How to think about the diagram**
   - The cleanest architecture diagram is a three-layer model:
     - **Cloudflare edge ingress** at the top,
     - **one Worker** in the middle handling auth, proxying, dashboard rendering, and config generation,
     - **D1 storage + optional Telegram/Analytics integrations** on the side.
   - The most important data flow is: browser or bot request → Worker route handling → D1 read/write → generated dashboard/subscription/proxy response.

Main entry points: [`_worker.js`](https://github.com/itsyebekhe/nahan/blob/main/_worker.js) (Worker core), [`wrangler.toml`](https://github.com/itsyebekhe/nahan/blob/main/wrangler.toml) (D1 store), [`dashboard.html`](https://github.com/itsyebekhe/nahan/blob/main/dashboard.html) (Dashboard UI), [`version`](https://github.com/itsyebekhe/nahan/tree/main/version) (Version)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_worker_entry["Worker core<br/>app runtime<br/>[_worker.js]"]
  node_route_mux["Route mux<br/>request router<br/>[_worker.js]"]
  node_auth_admin["Admin auth<br/>master-key gate<br/>[_worker.js]"]
  node_config_gen["Config builder<br/>subscription generator<br/>[_worker.js]"]
  node_protocol_templates["Proto templates<br/>config templates<br/>[singbox.json]"]
  node_v2_template["V2 template<br/>config template<br/>[vtwo.json]"]
  node_proxy_gateway["Gateway proxy<br/>vless/trojan proxy<br/>[_worker.js]"]
  node_kill_switch["Kill switch<br/>global pause<br/>[_worker.js]"]
end

subgraph group_state["State & integrations"]
  node_d1_store[("D1 store<br/>persistent sqlite<br/>[wrangler.toml]")]
  node_kv_table[("kv_store<br/>settings table")]
  node_telegram_bot["Telegram bot<br/>outbound control"]
  node_cloudflare_analytics["Analytics<br/>usage monitor"]
end

subgraph group_ui["Embedded UI"]
  node_camouflage_site["Camouflage page<br/>decoy response<br/>[index.html]"]
  node_dashboard_ui["Dashboard UI<br/>admin web ui<br/>[dashboard.html]"]
  node_subscription_ui["Subscription UI<br/>client config page<br/>[subscription.html]"]
end

subgraph group_support["Docs & ops"]
  node_wrangler_config["Wrangler config<br/>deploy manifest<br/>[wrangler.toml]"]
  node_version_file["Version<br/>release marker"]
  node_setup_script["Setup script<br/>ops helper<br/>[setup.sh]"]
  node_docs["Docs<br/>[README.md]"]
  node_docs_fa["Docs FA<br/>localized docs<br/>[README_FA.md]"]
end

node_cloudflare_edge(("Cloudflare Edge<br/>platform ingress"))

node_cloudflare_edge -->|"requests"| node_worker_entry
node_worker_entry -->|"dispatches"| node_route_mux
node_route_mux -->|"root"| node_camouflage_site
node_route_mux -->|"admin routes"| node_auth_admin
node_auth_admin -->|"serves"| node_dashboard_ui
node_route_mux -->|"sub route"| node_subscription_ui
node_worker_entry -->|"builds configs"| node_config_gen
node_config_gen -->|"uses"| node_protocol_templates
node_config_gen -->|"uses"| node_v2_template
node_worker_entry -->|"forwards"| node_proxy_gateway
node_proxy_gateway -.->|"can stop"| node_kill_switch
node_worker_entry -->|"reads/writes"| node_d1_store
node_d1_store -->|"contains"| node_kv_table
node_dashboard_ui -->|"updates"| node_d1_store
node_worker_entry -.->|"alerts"| node_telegram_bot
node_worker_entry -.->|"monitors"| node_cloudflare_analytics
node_wrangler_config -->|"binds"| node_d1_store
node_docs -.->|"explains"| node_worker_entry
node_docs_fa -.->|"explains"| node_worker_entry
node_setup_script -.->|"provisions"| node_wrangler_config
node_version_file -.->|"shows"| node_dashboard_ui

click node_worker_entry "https://github.com/itsyebekhe/nahan/blob/main/_worker.js"
click node_route_mux "https://github.com/itsyebekhe/nahan/blob/main/_worker.js"
click node_auth_admin "https://github.com/itsyebekhe/nahan/blob/main/_worker.js"
click node_camouflage_site "https://github.com/itsyebekhe/nahan/blob/main/index.html"
click node_dashboard_ui "https://github.com/itsyebekhe/nahan/blob/main/dashboard.html"
click node_subscription_ui "https://github.com/itsyebekhe/nahan/blob/main/subscription.html"
click node_config_gen "https://github.com/itsyebekhe/nahan/blob/main/_worker.js"
click node_protocol_templates "https://github.com/itsyebekhe/nahan/blob/main/singbox.json"
click node_v2_template "https://github.com/itsyebekhe/nahan/blob/main/vtwo.json"
click node_proxy_gateway "https://github.com/itsyebekhe/nahan/blob/main/_worker.js"
click node_kill_switch "https://github.com/itsyebekhe/nahan/blob/main/_worker.js"
click node_d1_store "https://github.com/itsyebekhe/nahan/blob/main/wrangler.toml"
click node_wrangler_config "https://github.com/itsyebekhe/nahan/blob/main/wrangler.toml"
click node_version_file "https://github.com/itsyebekhe/nahan/tree/main/version"
click node_setup_script "https://github.com/itsyebekhe/nahan/blob/main/setup.sh"
click node_docs "https://github.com/itsyebekhe/nahan/blob/main/README.md"
click node_docs_fa "https://github.com/itsyebekhe/nahan/blob/main/README_FA.md"

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_worker_entry,node_route_mux,node_auth_admin,node_config_gen,node_protocol_templates,node_v2_template,node_proxy_gateway,node_kill_switch toneBlue
class node_d1_store,node_kv_table,node_telegram_bot,node_cloudflare_analytics toneAmber
class node_camouflage_site,node_dashboard_ui,node_subscription_ui toneMint
class node_wrangler_config,node_version_file,node_setup_script,node_docs,node_docs_fa toneRose
class node_cloudflare_edge toneNeutral
```

## Components

### Runtime

Cloudflare Worker request handling, routing, proxying, and config generation.

- [Worker core](https://github.com/itsyebekhe/nahan/blob/main/_worker.js): app runtime · Main Cloudflare Worker entrypoint and application logic. · `_worker.js`
- [Route mux](https://github.com/itsyebekhe/nahan/blob/main/_worker.js): request router · Dispatches root, dashboard, subscription, and API actions. · `_worker.js`
- [Admin auth](https://github.com/itsyebekhe/nahan/blob/main/_worker.js): master-key gate · Protects dashboard and configuration actions with the stored master key. · `_worker.js`
- [Config builder](https://github.com/itsyebekhe/nahan/blob/main/_worker.js): subscription generator · Composes per-user and per-node client configs from stored settings and runtime data. · `_worker.js`
- [Proto templates](https://github.com/itsyebekhe/nahan/blob/main/singbox.json): config templates · Protocol-specific example or template config payloads. · `singbox.json`
- [V2 template](https://github.com/itsyebekhe/nahan/blob/main/vtwo.json): config template · Additional client config template or sample output. · `vtwo.json`
- [Gateway proxy](https://github.com/itsyebekhe/nahan/blob/main/_worker.js): vless/trojan proxy · Forwards and obscures traffic behind normal-looking HTTP behavior. · `_worker.js`
- [Kill switch](https://github.com/itsyebekhe/nahan/blob/main/_worker.js): global pause · Stops forwarding and can be triggered from the control plane. · `_worker.js`

### State & integrations

Persistent storage and outbound control-plane integrations.

- [D1 store](https://github.com/itsyebekhe/nahan/blob/main/wrangler.toml): persistent sqlite · Cloudflare D1 database used for durable settings and profiles. · `wrangler.toml`
- **kv_store**: settings table · Stores master key, API route, clean IP lists, and other dashboard state.
- **Telegram bot**: outbound control · Sends alerts, status, and control actions from the Worker.
- **Analytics**: usage monitor · Optional Cloudflare usage and quota monitoring integration.

### Embedded UI

Self-contained pages and assets served by the Worker.

- [Camouflage page](https://github.com/itsyebekhe/nahan/blob/main/index.html): decoy response · Serves a normal-looking public site at the root path. · `index.html`
- [Dashboard UI](https://github.com/itsyebekhe/nahan/blob/main/dashboard.html): admin web ui · Interactive settings and status interface served by the Worker. · `dashboard.html`
- [Subscription UI](https://github.com/itsyebekhe/nahan/blob/main/subscription.html): client config page · Human-readable subscription and QR-oriented page. · `subscription.html`

### Docs & ops

Documentation, release markers, and deployment helpers.

- [Wrangler config](https://github.com/itsyebekhe/nahan/blob/main/wrangler.toml): deploy manifest · Defines the Worker deployment and D1 binding. · `wrangler.toml`
- [Version](https://github.com/itsyebekhe/nahan/tree/main/version): release marker · Simple version or release reference used by the app. · `version`
- [Setup script](https://github.com/itsyebekhe/nahan/blob/main/setup.sh): ops helper · One-shot installation or provisioning helper. · `setup.sh`
- [Docs](https://github.com/itsyebekhe/nahan/blob/main/README.md): project docs · Primary README and help guides for operators. · `README.md`
- [Docs FA](https://github.com/itsyebekhe/nahan/blob/main/README_FA.md): localized docs · Persian-language documentation and help. · `README_FA.md`

### Other components

- **Cloudflare Edge**: platform ingress · Public entry point for the deployed Worker.

## Connections

- Cloudflare Edge → Worker core: requests · All public traffic enters the Worker at the edge.
- Worker core → Route mux: dispatches · The Worker routes requests by path and action.
- Route mux → Camouflage page: root · Serves a legitimate-looking public landing page.
- Route mux → Admin auth: admin routes · Protects dashboard and mutating configuration endpoints.
- Admin auth → Dashboard UI: serves · Returns the embedded management dashboard.
- Route mux → Subscription UI: sub route · Serves subscription views and client-facing config pages.
- Worker core → Config builder: builds configs · Generates subscription payloads and QR-ready outputs.
- Config builder → Proto templates: uses · Applies protocol-specific templates during generation.
- Config builder → V2 template: uses · Uses alternate client template/output shapes.
- Worker core → Gateway proxy: forwards · Acts as the reverse-proxy/gateway plane when needed.
- Gateway proxy → Kill switch: can stop · Forwarding can be globally paused.
- Worker core → D1 store: reads/writes · Persistent settings and profiles live in D1.
- D1 store → kv_store: contains · Stores dashboard state and configuration values.
- Dashboard UI → D1 store: updates · Dashboard changes are persisted immediately.
- Worker core → Telegram bot: alerts · Sends notifications and accepts control-plane actions.
- Worker core → Analytics: monitors · Optionally tracks request usage and quotas.
- Wrangler config → D1 store: binds · Declares the D1 database binding used by the Worker.
- Docs → Worker core: explains · Documents the single-worker architecture and operations.
- Docs FA → Worker core: explains · Localized documentation for the same runtime model.
- Setup script → Wrangler config: provisions · Helper for initial deployment and environment setup.
- Version → Dashboard UI: shows · Version marker can surface in the UI or update checks.
