How dichgrem/subhatch works
1. What this repo is
Subhatch is a single-service subscription manager that serves both an admin UI and subscription/config APIs from the same codebase. It is designed to run in two deployment modes: Cloudflare Workers or Node.js/Docker.
2. Top-level runtime split
The api/ directory contains the runtime entrypoints:
- api/cloudflare.js adapts the app to Workers and KV-style persistence.
- api/node.js adapts it to a local Node server, typically backed by filesystem storage under /data.
These are the main deployment boundaries; the rest of the code is shared and runtime-agnostic.
3. Core business logic
The src/ folder is where the real application logic lives. The main likely division is:
- src/core.js for domain operations and request handling
- src/kernel.js for the storage/runtime abstraction layer
- src/shared.js and src/tokens.js for common utilities and token/auth handling
This suggests a clean separation between HTTP/runtime adapters and the subscription/node management logic.
4. Data model and persistence
The app appears to manage:
- proxy nodes
- admin/auth state
- audit history
- upstream subscriptions
- exported config artifacts
Persistence is abstracted so the same features work with Cloudflare KV and local Node/Docker storage. The architecture is centered on a small mutable dataset rather than a separate database service.
5. Primary user-facing surfaces
There are two major surfaces:
- the web UI for admins
- the HTTP API/subscription endpoints for clients and automation
The UI is assembled from src/ui.html.js and src/css.js, implying server-generated HTML/CSS rather than a separate frontend app.
6. Admin workflow
The admin path likely goes: browser loads UI → login with password → receives a session token → token is stored client-side and sent as a bearer credential on API requests. The README emphasizes CSRF-safe token handling, brute-force rate limiting, and password hashing, so authentication is a first-class architectural boundary.
7. Node ingestion and management
Node management is a central subsystem:
- bulk paste of URIs
- CRUD operations for individual nodes
- QR/copy support per node
- node upload API
The tests under test/api/nodes.test.js and test/api/upload.test.js imply dedicated endpoints for both interactive admin use and machine ingestion.
8. Subscription and export pipeline
The subscription path is separate from admin CRUD:
- stored nodes are transformed into subscription output
- export formats are generated from the same underlying node set
- outputs include sing-box JSON and “momo” OpenWrt configs
Relevant modules here are src/export.js and src/momo.js, which indicate a transformation layer from internal node data to external config formats.
9. Upstream merge flow
src/upstream.js and the upstream tests show another important data source: remote subscription URLs. The system can fetch upstream data, merge it into the local export set, and expose the merged result. This is a distinct integration boundary with SSRF protection implied by the README.
10. Cross-cutting security controls
Security is not a separate service, but it is built into the app’s request handling:
- admin password verification
- session/token auth
- rate limiting on auth attempts
- SSRF protection for upstream fetches
- hidden-info mode for masking sensitive fields
These controls are likely enforced in shared middleware-like logic rather than at the UI layer.
11. Testing structure mirrors the architecture
The tests map cleanly onto the major subsystems:
- test/api/* covers endpoint behavior
- test/unit/* covers pure logic such as exports and shared helpers
- test/integration/full.test.js exercises the end-to-end flow
This is a good sign that the architecture is organized around stable domain modules with thin runtime adapters.
12. Operational/deployment boundary
Operationally, the repo supports two distinct deployment shapes:
- serverless worker with secret/env configuration and KV
- long-running Node/Docker container with mounted persistence
That means any architecture diagram should show the shared app logic in the middle, with two alternative edges for storage/runtime integration on either side.
Main entry points: core.js Core app · kernel.js Kernel · cloudflare.js Cloudflare · node.js Node server
Components 11
Runtime adapters
Deployment entrypoints for Cloudflare Workers and Node.js/Docker.
- Cloudflare · Workers adapter with KV-style persistence.
api/cloudflare.js - Node server · Local Node/Docker adapter with filesystem-backed storage.
api/node.js
Application core
Shared domain logic, storage abstraction, auth, and request handling.
- Core app · Main request handling and subscription/admin business logic.
src/core.js - Kernel · Abstraction layer for persistence and runtime-specific state.
src/kernel.js - Shared utils · Cross-cutting helpers used by core logic and request handling.
src/shared.js - Auth tokens · Session, token, and password-related security handling.
src/tokens.js
Presentation
Server-rendered admin UI and styles.
Data flows
Export, upstream merge, and config transformation pipelines.
- Export engine · Transforms stored nodes into subscription output formats.
src/export.js - Momo config · Formatter for OpenWrt momo output.
src/momo.js - Upstream merge · Fetches and merges remote subscription sources.
src/upstream.js
Connections 14
- Cloudflare → Core app: requests · Worker entrypoint hands HTTP requests to shared application logic.
- Node server → Core app: requests · Node entrypoint hands HTTP requests to shared application logic.
- Cloudflare → Kernel: kv storage · Cloudflare runtime adapts persistence through the kernel abstraction.
- Node server → Kernel: fs storage · Node runtime adapts persistence through the kernel abstraction.
- Core app → Shared utils: helpers · Core logic relies on shared utilities for common behaviors.
- Core app → Auth tokens: auth · Core request handling enforces session and password controls.
- Core app → Kernel: state · Core reads and mutates the managed subscription dataset through the kernel.
- Core app → Admin UI: renders · Admin workflows are served through server-rendered HTML.
- Core app → Styles: styles · UI rendering pulls in generated styles.
- Core app → Export engine: exports · Core exposes subscription and config output through the export pipeline.
- Export engine → Momo config: formats · Export engine delegates one output shape to momo formatting.
- Core app → Upstream merge: merge · Core integrates remote subscription sources into local output.
- Upstream merge → Kernel: stores · Merged upstream data is persisted through the storage abstraction.
- Auth tokens → Shared utils: security helpers · Auth logic shares low-level utilities with the common helper layer.