# dichgrem/subhatch architecture

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

- Interactive diagram: https://gitdiagram.com/dichgrem/subhatch
- Repository: https://github.com/dichgrem/subhatch

## Overview

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: [`src/core.js`](https://github.com/dichgrem/subhatch/blob/main/src/core.js) (Core app), [`src/kernel.js`](https://github.com/dichgrem/subhatch/blob/main/src/kernel.js) (Kernel), [`api/cloudflare.js`](https://github.com/dichgrem/subhatch/blob/main/api/cloudflare.js) (Cloudflare), [`api/node.js`](https://github.com/dichgrem/subhatch/blob/main/api/node.js) (Node server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime adapters"]
  node_api_cloudflare["Cloudflare<br/>worker entrypoint<br/>[cloudflare.js]"]
  node_api_node["Node server<br/>node entrypoint<br/>[node.js]"]
end

subgraph group_core["Application core"]
  node_core["Core app<br/>domain router<br/>[core.js]"]
  node_kernel[("Kernel<br/>storage/runtime<br/>[kernel.js]")]
  node_shared["Shared utils<br/>common helpers<br/>[shared.js]"]
  node_tokens["Auth tokens<br/>auth/security<br/>[tokens.js]"]
end

subgraph group_presentation["Presentation"]
  node_ui_html["Admin UI<br/>server-rendered ui<br/>[ui.html.js]"]
  node_css["Styles<br/>ui styling<br/>[css.js]"]
end

subgraph group_integration["Data flows"]
  node_export["Export engine<br/>config transform<br/>[export.js]"]
  node_momo["Momo config<br/>export format<br/>[momo.js]"]
  node_upstream["Upstream merge<br/>remote ingest<br/>[upstream.js]"]
end

node_api_cloudflare -->|"requests"| node_core
node_api_node -->|"requests"| node_core
node_api_cloudflare -->|"kv storage"| node_kernel
node_api_node -->|"fs storage"| node_kernel
node_core -->|"helpers"| node_shared
node_core -->|"auth"| node_tokens
node_core -->|"state"| node_kernel
node_core -->|"renders"| node_ui_html
node_core -->|"styles"| node_css
node_core -->|"exports"| node_export
node_export -->|"formats"| node_momo
node_core -->|"merge"| node_upstream
node_upstream -->|"stores"| node_kernel
node_tokens -->|"security helpers"| node_shared

click node_api_cloudflare "https://github.com/dichgrem/subhatch/blob/main/api/cloudflare.js"
click node_api_node "https://github.com/dichgrem/subhatch/blob/main/api/node.js"
click node_core "https://github.com/dichgrem/subhatch/blob/main/src/core.js"
click node_kernel "https://github.com/dichgrem/subhatch/blob/main/src/kernel.js"
click node_shared "https://github.com/dichgrem/subhatch/blob/main/src/shared.js"
click node_tokens "https://github.com/dichgrem/subhatch/blob/main/src/tokens.js"
click node_ui_html "https://github.com/dichgrem/subhatch/blob/main/src/ui.html.js"
click node_css "https://github.com/dichgrem/subhatch/blob/main/src/css.js"
click node_export "https://github.com/dichgrem/subhatch/blob/main/src/export.js"
click node_momo "https://github.com/dichgrem/subhatch/blob/main/src/momo.js"
click node_upstream "https://github.com/dichgrem/subhatch/blob/main/src/upstream.js"

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_api_cloudflare,node_api_node toneBlue
class node_core,node_kernel,node_shared,node_tokens toneAmber
class node_ui_html,node_css toneMint
class node_export,node_momo,node_upstream toneRose
```

## Components

### Runtime adapters

Deployment entrypoints for Cloudflare Workers and Node.js/Docker.

- [Cloudflare](https://github.com/dichgrem/subhatch/blob/main/api/cloudflare.js): worker entrypoint · Workers adapter with KV-style persistence. · `api/cloudflare.js`
- [Node server](https://github.com/dichgrem/subhatch/blob/main/api/node.js): node entrypoint · Local Node/Docker adapter with filesystem-backed storage. · `api/node.js`

### Application core

Shared domain logic, storage abstraction, auth, and request handling.

- [Core app](https://github.com/dichgrem/subhatch/blob/main/src/core.js): domain router · Main request handling and subscription/admin business logic. · `src/core.js`
- [Kernel](https://github.com/dichgrem/subhatch/blob/main/src/kernel.js): storage/runtime · Abstraction layer for persistence and runtime-specific state. · `src/kernel.js`
- [Shared utils](https://github.com/dichgrem/subhatch/blob/main/src/shared.js): common helpers · Cross-cutting helpers used by core logic and request handling. · `src/shared.js`
- [Auth tokens](https://github.com/dichgrem/subhatch/blob/main/src/tokens.js): auth/security · Session, token, and password-related security handling. · `src/tokens.js`

### Presentation

Server-rendered admin UI and styles.

- [Admin UI](https://github.com/dichgrem/subhatch/blob/main/src/ui.html.js): server-rendered ui · HTML assembly for the admin interface. · `src/ui.html.js`
- [Styles](https://github.com/dichgrem/subhatch/blob/main/src/css.js): ui styling · Generated CSS for the server-rendered UI. · `src/css.js`

### Data flows

Export, upstream merge, and config transformation pipelines.

- [Export engine](https://github.com/dichgrem/subhatch/blob/main/src/export.js): config transform · Transforms stored nodes into subscription output formats. · `src/export.js`
- [Momo config](https://github.com/dichgrem/subhatch/blob/main/src/momo.js): export format · Formatter for OpenWrt momo output. · `src/momo.js`
- [Upstream merge](https://github.com/dichgrem/subhatch/blob/main/src/upstream.js): remote ingest · Fetches and merges remote subscription sources. · `src/upstream.js`

## Connections

- 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.
