How itsyebekhe/nahan works
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 Worker core · wrangler.toml D1 store · dashboard.html Dashboard UI · version Version
Components 21
Runtime
Cloudflare Worker request handling, routing, proxying, and config generation.
- Worker core · Main Cloudflare Worker entrypoint and application logic.
_worker.js - Route mux · Dispatches root, dashboard, subscription, and API actions.
_worker.js - Admin auth · Protects dashboard and configuration actions with the stored master key.
_worker.js - Config builder · Composes per-user and per-node client configs from stored settings and runtime data.
_worker.js - Proto templates · Protocol-specific example or template config payloads.
singbox.json - V2 template · Additional client config template or sample output.
vtwo.json - Gateway proxy · Forwards and obscures traffic behind normal-looking HTTP behavior.
_worker.js - Kill switch · Stops forwarding and can be triggered from the control plane.
_worker.js
State & integrations
Persistent storage and outbound control-plane integrations.
- D1 store · Cloudflare D1 database used for durable settings and profiles.
wrangler.toml - kv_store · Stores master key, API route, clean IP lists, and other dashboard state.
- Telegram bot · Sends alerts, status, and control actions from the Worker.
- Analytics · Optional Cloudflare usage and quota monitoring integration.
Embedded UI
Self-contained pages and assets served by the Worker.
- Camouflage page · Serves a normal-looking public site at the root path.
index.html - Dashboard UI · Interactive settings and status interface served by the Worker.
dashboard.html - Subscription UI · Human-readable subscription and QR-oriented page.
subscription.html
Docs & ops
Documentation, release markers, and deployment helpers.
- Wrangler config · Defines the Worker deployment and D1 binding.
wrangler.toml - Version · Simple version or release reference used by the app.
version - Setup script · One-shot installation or provisioning helper.
setup.sh - Docs · Primary README and help guides for operators.
README.md - Docs FA · Persian-language documentation and help.
README_FA.md
Other components
- Cloudflare Edge · Public entry point for the deployed Worker.
Connections 21
- 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.