# mer30hamid/v2ray-sub2json-worker architecture

> Architecture diagram of the GitHub repository mer30hamid/v2ray-sub2json-worker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mer30hamid/v2ray-sub2json-worker
- Repository: https://github.com/mer30hamid/v2ray-sub2json-worker

## Overview

##### Project type and purpose
- This is a full-stack Cloudflare Worker application built with SvelteKit.
- Purpose: Provide a web UI for converting V2Ray subscription links or raw configs into a unified JSON format compatible with XRAY-based clients (V2RayN/V2RayNG).

##### File structure
- Top-level:
- .github/workflows – CI pipelines (build, deploy)
- wrangler.jsonc – Cloudflare Worker configuration
- tree.cjs, zip.cjs – custom build/zipping scripts
- project.inlang – i18n settings, messages/en.json & messages/fa-ir.json
- src/ – SvelteKit application
- src/lib – shared modules
- components (Button, Textarea, SettingsLimit)
- utils (conversion.ts, helpers.ts)
- src/routes – SvelteKit routing
- /convert (+page.svelte): frontend form UI
- /sub2json (+server.ts): API endpoint for doing the conversion
- static/ – static assets
- package*.json, tsconfig.json, vite.config.ts, svelte.config.js – build & type configurations

##### README
- Confirms this is a Cloudflare Worker that exposes:
- A single‐page form under /convert
- A POST/GET API under /sub2json to do the actual subscription fetch & JSON conversion
- Lists supported protocols, features (load-balancing, unblocking, raw config conversion)
- CI/CD via GitHub Actions to build & deploy to Workers

a. Main components
- Client Browser (User Interface)
- Cloudflare Worker (SvelteKit runtime)
– Frontend routes (/convert)
– Backend/API route (/sub2json)
- Library Modules
– conversion.ts, helpers.ts (business logic for parsing & transforming)
– UI Components
- External V2Ray subscription endpoints (URLs provided by user)
- GitHub Actions (CI/CD) → Wrangler → Cloudflare Workers

b. Relationships & data flows
1. User opens https://<worker>/convert → Worker serves SvelteKit page
2. User enters one or more subscription URLs or raw configs and clicks “Convert & Copy”
3. Frontend issues a fetch to /sub2json with user input
4. Worker’s /sub2json handler:
– Calls conversion utils to fetch each external URL (over HTTP)
– Parses and merges configs, applies load-balancing/unblocking logic
– Returns a JSON payload
5. Frontend receives JSON, displays results and copies to clipboard
6. (Optional) User opens raw JSON via “Open” button

c. Architectural patterns & design principles
- Single Worker hosting both UI (SSR) and API (Edge functions)
- Separation of concerns:
- UI components in src/lib/components
- Business logic in src/lib/utils
- Routing by SvelteKit conventions (routes directory)
- CI/CD pipeline automates build → zip → deploy

d. Key technologies & frameworks
- Cloudflare Workers (Edge runtime)
- SvelteKit (front & server‐side routing)
- TypeScript (type safety)
- GitHub Actions (build & deploy workflows)
- Wrangler (Cloudflare CLI)

##### Final recommendations
- Every distinct role: UI, API, business logic modules, external systems, and CI/CD
- SvelteKit’s frontend & API under a single Cloudflare Worker boundary
- Detail any important parameters (e.g., supported protocols, load balancing logic) next to the conversion module

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser UI
    BrowserUI["Browser UI<br/>(SvelteKit Frontend)"]:::frontend
    click BrowserUI "https://github.com/mer30hamid/v2ray-sub2json-worker/blob/main/src/routes/convert/+page.svelte"

    %% Cloudflare Worker Boundary
    subgraph "Cloudflare Worker" 
        direction TB
        Frontend["SvelteKit Frontend<br/>(/convert)"]:::server
        click Frontend "https://github.com/mer30hamid/v2ray-sub2json-worker/blob/main/src/routes/convert/+page.svelte"
        APIHandler["/sub2json API Handler"]:::server
        click APIHandler "https://github.com/mer30hamid/v2ray-sub2json-worker/blob/main/src/routes/sub2json/+server.ts"
    end

    %% Business Logic Modules
    subgraph "Library Modules" 
        direction TB
        Conversion["conversion.ts"]:::logic
        click Conversion "https://github.com/mer30hamid/v2ray-sub2json-worker/blob/main/src/lib/utils/conversion.ts"
        Helpers["helpers.ts"]:::logic
        click Helpers "https://github.com/mer30hamid/v2ray-sub2json-worker/blob/main/src/lib/utils/helpers.ts"
        Button["Button.svelte"]:::component
        click Button "https://github.com/mer30hamid/v2ray-sub2json-worker/blob/main/src/lib/components/Button.svelte"
        Textarea["Textarea.svelte"]:::component
        click Textarea "https://github.com/mer30hamid/v2ray-sub2json-worker/blob/main/src/lib/components/Textarea.svelte"
        SettingsLimit["SettingsLimit.svelte"]:::component
        click SettingsLimit "https://github.com/mer30hamid/v2ray-sub2json-worker/blob/main/src/lib/components/SettingsLimit.svelte"
    end

    %% External Subscriptions
    External["External Subscription Endpoints"]:::external

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline" 
        direction TB
        BuildYML[".github/workflows/build.yml"]:::cicd
        click BuildYML "https://github.com/mer30hamid/v2ray-sub2json-worker/blob/main/.github/workflows/build.yml"
        DeployYML[".github/workflows/deploy.yml"]:::cicd
        click DeployYML "https://github.com/mer30hamid/v2ray-sub2json-worker/blob/main/.github/workflows/deploy.yml"
        Wrangler["wrangler.jsonc"]:::cicd
        click Wrangler "https://github.com/mer30hamid/v2ray-sub2json-worker/blob/main/wrangler.jsonc"
        Tree["tree.cjs"]:::cicd
        click Tree "https://github.com/mer30hamid/v2ray-sub2json-worker/blob/main/tree.cjs"
        Zip["zip.cjs"]:::cicd
        click Zip "https://github.com/mer30hamid/v2ray-sub2json-worker/blob/main/zip.cjs"
    end

    %% Configuration Files
    subgraph "Configuration & Tooling" 
        direction TB
        SvelteConfig["svelte.config.js"]:::config
        click SvelteConfig "https://github.com/mer30hamid/v2ray-sub2json-worker/blob/main/svelte.config.js"
        ViteConfig["vite.config.ts"]:::config
        click ViteConfig "https://github.com/mer30hamid/v2ray-sub2json-worker/blob/main/vite.config.ts"
        TSConfig["tsconfig.json"]:::config
        click TSConfig "https://github.com/mer30hamid/v2ray-sub2json-worker/blob/main/tsconfig.json"
        PackageJSON["package.json"]:::config
        click PackageJSON "https://github.com/mer30hamid/v2ray-sub2json-worker/blob/main/package.json"
        PackageLock["package-lock.json"]:::config
        click PackageLock "https://github.com/mer30hamid/v2ray-sub2json-worker/blob/main/package-lock.json"
        Layout["Layout & Home"]:::frontend
        click Layout "https://github.com/mer30hamid/v2ray-sub2json-worker/blob/main/src/routes/+layout.svelte"
        HomePage["Home Page"]:::frontend
        click HomePage "https://github.com/mer30hamid/v2ray-sub2json-worker/blob/main/src/routes/+page.svelte"
    end

    %% Internationalization
    subgraph "Internationalization" 
        direction TB
        EN["messages/en.json"]:::i18n
        click EN "https://github.com/mer30hamid/v2ray-sub2json-worker/blob/main/messages/en.json"
        FA["messages/fa-ir.json"]:::i18n
        click FA "https://github.com/mer30hamid/v2ray-sub2json-worker/blob/main/messages/fa-ir.json"
        I18n["project.inlang/settings.json"]:::i18n
        click I18n "https://github.com/mer30hamid/v2ray-sub2json-worker/blob/main/project.inlang/settings.json"
    end

    %% Flows
    BrowserUI -->|"HTTP GET /convert"| Frontend
    Frontend -->|"User Input"| APIHandler
    APIHandler -->|"fetch() HTTP GET"| External
    APIHandler -->|"uses"| Conversion
    APIHandler -->|"uses"| Helpers
    Frontend -->|"uses UI components"| Button
    Frontend -->|"uses UI components"| Textarea
    Frontend -->|"uses UI components"| SettingsLimit
    APIHandler -->|"returns JSON"| Frontend

    BuildYML -->|build| Wrangler
    DeployYML -->|deploy| Wrangler
    Wrangler -->|deploy via Workers CLI| Frontend
    Wrangler -->|deploy via Workers CLI| APIHandler

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#006064;
    classDef server fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32;
    classDef logic fill:#F1F8E9,stroke:#558B2F,color:#558B2F;
    classDef component fill:#E3F2FD,stroke:#1565C0,color:#1565C0;
    classDef external fill:#FFF3E0,stroke:#EF6C00,color:#E65100;
    classDef cicd fill:#ECEFF1,stroke:#546E7A,color:#37474F;
    classDef config fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C;
    classDef i18n fill:#FBE9E7,stroke:#BF360C,color:#BF360C;
```
