# sub-store-org/sub-store architecture

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

- Interactive diagram: https://gitdiagram.com/sub-store-org/sub-store
- Repository: https://github.com/sub-store-org/sub-store

## Overview

Sub-Store is a subscription-management backend: users submit subscription or resource inputs, preview or convert them into proxy-platform formats, and manage collections, files, and synchronized artifacts through REST APIs. The central conversion path normalizes diverse proxy inputs and produces target-specific outputs; separate rule utilities and Loon resource parsing support formatting and resource-script capabilities. REST route internals and several documented product subsystems were not sampled, so their connections are shown only where the README or excerpts establish them.

Main entry points: [`backend/src/restful/index.js`](https://github.com/sub-store-org/sub-store/blob/master/backend/src/restful/index.js) (REST routes), [`backend/src/core/proxy-utils/index.js`](https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/index.js) (Proxy conversion engine), [`backend/src/restful/preview.js`](https://github.com/sub-store-org/sub-store/blob/master/backend/src/restful/preview.js) (Preview subscriptions), [`backend/src/core/proxy-utils/producers/index.js`](https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/producers/index.js) (Target format producers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["REST API"]
  node_rest["REST routes<br/>[index.js]"]
  node_preview["Preview subscriptions<br/>[preview.js]"]
  node_download["Subscription download<br/>[download.js]"]
  node_sync["Sync and artifacts<br/>[sync.js]"]
  node_files["File management<br/>[file.js]"]
end

subgraph group_conversion["Proxy Conversion"]
  node_proxy["Proxy conversion engine<br/>[index.js]"]
  node_parsers["Proxy input parsers<br/>[index.js]"]
  node_parsergrammars["QX Loon Surge grammars<br/>[loon.js]"]
  node_producers["Target format producers<br/>[index.js]"]
  node_singbox["sing-box producer<br/>[sing-box.js]"]
  node_uri["URI producer<br/>[uri.js]"]
  node_clashmeta["Clash.Meta producer<br/>[clashmeta.js]"]
  node_preprocessors["Proxy preprocessors<br/>[index.js]"]
  node_processors["Proxy processors<br/>[index.js]"]
  node_transport["Transport path utilities<br/>[transport-path.js]"]
  node_vmess["VMess security normalization<br/>[vmess-security.js]"]
  node_ech["ECH utilities<br/>[ech-utils.js]"]
end

subgraph group_format["Rules And Resources"]
  node_rules["Rule utilities<br/>[index.js]"]
  node_ruleparser["Universal rule parser<br/>[parsers.js]"]
  node_loonresource["Loon resource parser"]
end

subgraph group_runtime["State And Runtime"]
  node_entry["Backend entry<br/>[main.js]"]
  node_cron["Artifact sync scheduler"]
  node_db[("Application database<br/>[database.js]")]
  node_downloadutil["Remote download utility<br/>[download.js]"]
  node_migration["State migration<br/>[migration.js]"]
end

node_user(("Subscription user"))

node_user -->|"sends requests"| node_rest
node_entry -->|"runs migration"| node_migration
node_entry -->|"starts server"| node_rest
node_rest -.->|"routes requests"| node_preview
node_preview -->|"fetches sources"| node_downloadutil
node_preview -.->|"converts subscriptions"| node_proxy
node_preview -->|"looks up subscriptions"| node_db
node_rest -.->|"routes downloads"| node_download
node_rest -.->|"routes synchronization"| node_sync
node_rest -.->|"routes file operations"| node_files
node_proxy -->|"parses inputs"| node_parsers
node_proxy -->|"preprocesses inputs"| node_preprocessors
node_proxy -->|"processes proxies"| node_processors
node_proxy -->|"selects target producer"| node_producers
node_parsers -->|"uses grammars"| node_parsergrammars
node_producers -->|"registers producer"| node_singbox
node_producers -->|"registers producer"| node_uri
node_producers -->|"registers producer"| node_clashmeta
node_uri -->|"normalizes paths"| node_transport
node_uri -->|"normalizes security"| node_vmess
node_uri -->|"builds ECH config"| node_ech
node_singbox -->|"parses path values"| node_transport
node_clashmeta -.->|"uses path utilities"| node_transport
node_loonresource -->|"parses and produces rules"| node_rules
node_rules -->|"uses parser"| node_ruleparser
node_loonresource -->|"fetches resources"| node_downloadutil
node_cron -.->|"schedules artifact sync"| node_sync

click node_entry "https://github.com/sub-store-org/sub-store/blob/master/backend/src/main.js"
click node_rest "https://github.com/sub-store-org/sub-store/blob/master/backend/src/restful/index.js"
click node_preview "https://github.com/sub-store-org/sub-store/blob/master/backend/src/restful/preview.js"
click node_download "https://github.com/sub-store-org/sub-store/blob/master/backend/src/restful/download.js"
click node_sync "https://github.com/sub-store-org/sub-store/blob/master/backend/src/restful/sync.js"
click node_files "https://github.com/sub-store-org/sub-store/blob/master/backend/src/restful/file.js"
click node_proxy "https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/index.js"
click node_parsers "https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/parsers/index.js"
click node_parsergrammars "https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/parsers/peggy/loon.js"
click node_producers "https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/producers/index.js"
click node_singbox "https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/producers/sing-box.js"
click node_uri "https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/producers/uri.js"
click node_clashmeta "https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/producers/clashmeta.js"
click node_preprocessors "https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/preprocessors/index.js"
click node_processors "https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/processors/index.js"
click node_transport "https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/transport-path.js"
click node_vmess "https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/vmess-security.js"
click node_ech "https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/ech-utils.js"
click node_rules "https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/rule-utils/index.js"
click node_ruleparser "https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/rule-utils/parsers.js"
click node_loonresource "https://github.com/sub-store-org/sub-store/blob/master/backend/src/products/resource-parser.loon.js"
click node_cron "https://github.com/sub-store-org/sub-store/blob/master/backend/src/products/cron-sync-artifacts.js"
click node_db "https://github.com/sub-store-org/sub-store/blob/master/backend/src/utils/database.js"
click node_downloadutil "https://github.com/sub-store-org/sub-store/blob/master/backend/src/utils/download.js"
click node_migration "https://github.com/sub-store-org/sub-store/blob/master/backend/src/utils/migration.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_rest,node_preview,node_download,node_sync,node_files,node_user toneBlue
class node_proxy,node_parsers,node_parsergrammars,node_producers,node_singbox,node_uri,node_clashmeta,node_preprocessors,node_processors,node_transport,node_vmess,node_ech toneAmber
class node_rules,node_ruleparser,node_loonresource toneMint
class node_entry,node_cron,node_db,node_downloadutil,node_migration toneRose
```

## Components

### REST API

- [REST routes](https://github.com/sub-store-org/sub-store/blob/master/backend/src/restful/index.js): `backend/src/restful/index.js`
- [Preview subscriptions](https://github.com/sub-store-org/sub-store/blob/master/backend/src/restful/preview.js): `backend/src/restful/preview.js`
- [Subscription download](https://github.com/sub-store-org/sub-store/blob/master/backend/src/restful/download.js): `backend/src/restful/download.js`
- [Sync and artifacts](https://github.com/sub-store-org/sub-store/blob/master/backend/src/restful/sync.js): `backend/src/restful/sync.js`
- [File management](https://github.com/sub-store-org/sub-store/blob/master/backend/src/restful/file.js): `backend/src/restful/file.js`

### Proxy Conversion

- [Proxy conversion engine](https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/index.js): `backend/src/core/proxy-utils/index.js`
- [Proxy input parsers](https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/parsers/index.js): `backend/src/core/proxy-utils/parsers/index.js`
- [QX Loon Surge grammars](https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/parsers/peggy/loon.js): `backend/src/core/proxy-utils/parsers/peggy/loon.js`
- [Target format producers](https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/producers/index.js): `backend/src/core/proxy-utils/producers/index.js`
- [sing-box producer](https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/producers/sing-box.js): `backend/src/core/proxy-utils/producers/sing-box.js`
- [URI producer](https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/producers/uri.js): `backend/src/core/proxy-utils/producers/uri.js`
- [Clash.Meta producer](https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/producers/clashmeta.js): `backend/src/core/proxy-utils/producers/clashmeta.js`
- [Proxy preprocessors](https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/preprocessors/index.js): `backend/src/core/proxy-utils/preprocessors/index.js`
- [Proxy processors](https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/processors/index.js): `backend/src/core/proxy-utils/processors/index.js`
- [Transport path utilities](https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/transport-path.js): `backend/src/core/proxy-utils/transport-path.js`
- [VMess security normalization](https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/vmess-security.js): `backend/src/core/proxy-utils/vmess-security.js`
- [ECH utilities](https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/proxy-utils/ech-utils.js): `backend/src/core/proxy-utils/ech-utils.js`

### Rules And Resources

- [Rule utilities](https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/rule-utils/index.js): `backend/src/core/rule-utils/index.js`
- [Universal rule parser](https://github.com/sub-store-org/sub-store/blob/master/backend/src/core/rule-utils/parsers.js): `backend/src/core/rule-utils/parsers.js`
- [Loon resource parser](https://github.com/sub-store-org/sub-store/blob/master/backend/src/products/resource-parser.loon.js): `backend/src/products/resource-parser.loon.js`

### State And Runtime

- [Backend entry](https://github.com/sub-store-org/sub-store/blob/master/backend/src/main.js): `backend/src/main.js`
- [Artifact sync scheduler](https://github.com/sub-store-org/sub-store/blob/master/backend/src/products/cron-sync-artifacts.js): `backend/src/products/cron-sync-artifacts.js`
- [Application database](https://github.com/sub-store-org/sub-store/blob/master/backend/src/utils/database.js): `backend/src/utils/database.js`
- [Remote download utility](https://github.com/sub-store-org/sub-store/blob/master/backend/src/utils/download.js): `backend/src/utils/download.js`
- [State migration](https://github.com/sub-store-org/sub-store/blob/master/backend/src/utils/migration.js): `backend/src/utils/migration.js`

### Other components

- **Subscription user**

## Connections

- Subscription user → REST routes: sends requests
- Backend entry → State migration: runs migration (evidence: `backend/src/main.js`)
- Backend entry → REST routes: starts server (evidence: `backend/src/main.js`)
- REST routes → Preview subscriptions: routes requests
- Preview subscriptions → Remote download utility: fetches sources (evidence: `backend/src/restful/preview.js`)
- Preview subscriptions → Proxy conversion engine: converts subscriptions
- Preview subscriptions → Application database: looks up subscriptions (evidence: `backend/src/restful/preview.js`)
- REST routes → Subscription download: routes downloads
- REST routes → Sync and artifacts: routes synchronization
- REST routes → File management: routes file operations
- Proxy conversion engine → Proxy input parsers: parses inputs (evidence: `backend/src/core/proxy-utils/index.js`)
- Proxy conversion engine → Proxy preprocessors: preprocesses inputs (evidence: `backend/src/core/proxy-utils/index.js`)
- Proxy conversion engine → Proxy processors: processes proxies (evidence: `backend/src/core/proxy-utils/index.js`)
- Proxy conversion engine → Target format producers: selects target producer (evidence: `backend/src/core/proxy-utils/index.js`)
- Proxy input parsers → QX Loon Surge grammars: uses grammars (evidence: `backend/src/core/proxy-utils/parsers/index.js`)
- Target format producers → sing-box producer: registers producer (evidence: `backend/src/core/proxy-utils/producers/index.js`)
- Target format producers → URI producer: registers producer (evidence: `backend/src/core/proxy-utils/producers/index.js`)
- Target format producers → Clash.Meta producer: registers producer (evidence: `backend/src/core/proxy-utils/producers/index.js`)
- URI producer → Transport path utilities: normalizes paths (evidence: `backend/src/core/proxy-utils/producers/uri.js`)
- URI producer → VMess security normalization: normalizes security (evidence: `backend/src/core/proxy-utils/producers/uri.js`)
- URI producer → ECH utilities: builds ECH config (evidence: `backend/src/core/proxy-utils/producers/uri.js`)
- sing-box producer → Transport path utilities: parses path values (evidence: `backend/src/core/proxy-utils/producers/sing-box.js`)
- Clash.Meta producer → Transport path utilities: uses path utilities (evidence: `backend/src/core/proxy-utils/producers/clashmeta.js`)
- Loon resource parser → Rule utilities: parses and produces rules (evidence: `backend/src/products/resource-parser.loon.js`)
- Rule utilities → Universal rule parser: uses parser (evidence: `backend/src/core/rule-utils/index.js`)
- Loon resource parser → Remote download utility: fetches resources (evidence: `backend/src/products/resource-parser.loon.js`)
- Artifact sync scheduler → Sync and artifacts: schedules artifact sync
