# xlordgrim/3x-sub architecture

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

- Interactive diagram: https://gitdiagram.com/xlordgrim/3x-sub
- Repository: https://github.com/xlordgrim/3x-sub

## Overview

#### Purpose and Deployment Model
3X-SUB replaces or customizes the subscription page served by an existing 3X-UI installation (v2.8.4+). It is not a standalone web application: shell scripts install repository assets into the 3X-UI panel environment, while the page relies on that host’s subscription and monitoring endpoints.

Primary operational entry points:
- `install.sh` installs/updates the custom page, with `--fa` and `--zh` language options.
- `uninstall.sh` restores the default subscription experience, updating the host panel as part of recovery.
- `test.html` is a browser-accessible/demo-oriented entry point outside the installed panel path.

#### Installer and Host Integration
`install.sh` is the critical integration boundary. It targets AMD64 and ARM64 3X-UI servers and deploys frontend assets into paths corresponding to the panel’s subscription-page structure. Its responsibilities are expected to include fetching/copying assets, selecting localization, and arranging the page beneath the panel’s served static content.

The installed page hierarchy mirrors 3X-UI’s internal web layout:
- `web/html/settings/panel/subscription/subpage.html`
- `web/assets/css/premium.css`
- `web/assets/js/subscription.js`

The custom frontend must remain compatible with 3X-UI’s rendered context, routing, authentication/session behavior, and available APIs rather than owning those concerns.

#### Subscription Page Presentation Layer
`web/html/settings/panel/subscription/subpage.html` is the primary installed UI document. It defines the subscription subpage embedded or served within the 3X-UI panel structure.

The presentation system is separated into:
- HTML structure and panel integration: `web/html/settings/panel/subscription/subpage.html`
- Custom visual language—dark/light themes, glass styling, transitions, responsive layout, adaptive themes: `web/assets/css/premium.css`

This boundary permits page markup and theme behavior to evolve independently of installer mechanics.

#### Client-Side Subscription Controller
`web/assets/js/subscription.js` is the browser control plane for the page. Based on the project scope, it coordinates:
- subscription metadata and configuration-link display;
- QR-code and status UI updates;
- theme selection and interactive notifications;
- efficient polling for live server CPU, RAM, and network stats.

It consumes data from the hosting 3X-UI environment and renders it into the installed subscription page. No independent backend or external API service is represented in the repository.

#### Runtime Data Flow
1. An operator executes `install.sh` on a 3X-UI server.
2. Deployment places the subpage, stylesheet, and JavaScript in panel-compatible static locations.
3. A client opens the subscription page served by 3X-UI.
4. `subpage.html` loads `premium.css` and `subscription.js`.
5. JavaScript reads host-provided subscription/server data and periodically refreshes dashboard and server-stat UI.
6. Users consume configuration links, QR codes, quota/status information, and current server telemetry.

The primary trust and data boundary is between browser-side custom code and authenticated/available 3X-UI endpoints; this repo does not introduce a separate service layer.

#### Infrastructure and Delivery
The runtime infrastructure is a Linux-hosted 3X-UI panel managed alongside system services; the README identifies systemd integration as part of the installation model. GitHub Actions contains a custom-panel build workflow:
- `.github/workflows/build-custom-xui.yml`

Repository-hosted static assets are also used for the public demo/documentation surface, including screenshots under `screenshots`. The live demo is externally hosted via GitHub Pages, while production installation is performed directly on the target 3X-UI server.

Main entry points: [`install.sh`](https://github.com/xlordgrim/3x-sub/blob/main/install.sh) (Installer), [`web/assets/js/subscription.js`](https://github.com/xlordgrim/3x-sub/blob/main/web/assets/js/subscription.js) (Subscription controller), [`web/html/settings/panel/subscription/subpage.html`](https://github.com/xlordgrim/3x-sub/blob/main/web/html/settings/panel/subscription/subpage.html) (Subscription subpage), [`web/assets/css/premium.css`](https://github.com/xlordgrim/3x-sub/blob/main/web/assets/css/premium.css) (Premium theme)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deployment["Deployment"]
  node_install["Installer<br/>shell script<br/>[install.sh]"]
  node_uninstall["Uninstaller<br/>shell script<br/>[uninstall.sh]"]
  node_systemd{{"System services<br/>systemd"}}
end

subgraph group_frontend["Installed frontend"]
  node_subpage["Subscription subpage<br/>HTML page<br/>[subpage.html]"]
  node_styles["Premium theme<br/>CSS<br/>[premium.css]"]
  node_controller["Subscription controller<br/>browser JavaScript<br/>[subscription.js]"]
  node_browser(("Subscriber browser<br/>browser client"))
end

subgraph group_host["3X-UI host runtime"]
  node_panel["3X-UI panel<br/>host application"]
  node_hostdata[("Subscription &amp; monitoring endpoints<br/>host APIs")]
end

subgraph group_delivery["Repository delivery"]
  node_workflow{{"Custom panel build<br/>GitHub Actions workflow"}}
  node_demo["Demo page<br/>HTML entry point<br/>[test.html]"]
  node_screenshots["Screenshots<br/>static assets"]
  node_githubpages["GitHub Pages demo<br/>static hosting"]
end

node_install -->|"deploys assets to"| node_panel
node_uninstall -->|"restores default page"| node_panel
node_systemd -->|"manages runtime"| node_panel
node_install -->|"places"| node_subpage
node_install -->|"places"| node_styles
node_install -->|"places"| node_controller
node_panel -->|"serves"| node_subpage
node_subpage -->|"loads"| node_styles
node_subpage -->|"loads"| node_controller
node_browser -->|"opens subscription page"| node_panel
node_controller -->|"reads and polls"| node_hostdata
node_hostdata -->|"subscription and telemetry"| node_controller
node_controller -->|"updates UI"| node_browser
node_workflow -.->|"delivers release assets"| node_install
node_demo -->|"published as"| node_githubpages
node_screenshots -.->|"supports demo/docs"| node_githubpages

click node_install "https://github.com/xlordgrim/3x-sub/blob/main/install.sh"
click node_uninstall "https://github.com/xlordgrim/3x-sub/blob/main/uninstall.sh"
click node_subpage "https://github.com/xlordgrim/3x-sub/blob/main/web/html/settings/panel/subscription/subpage.html"
click node_styles "https://github.com/xlordgrim/3x-sub/blob/main/web/assets/css/premium.css"
click node_controller "https://github.com/xlordgrim/3x-sub/blob/main/web/assets/js/subscription.js"
click node_workflow "https://github.com/xlordgrim/3x-sub/blob/main/.github/workflows/build-custom-xui.yml"
click node_demo "https://github.com/xlordgrim/3x-sub/blob/main/test.html"
click node_screenshots "https://github.com/xlordgrim/3x-sub/tree/main/screenshots"

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_install,node_uninstall,node_systemd toneBlue
class node_subpage,node_styles,node_controller,node_browser toneAmber
class node_panel,node_hostdata toneMint
class node_workflow,node_demo,node_screenshots,node_githubpages toneRose
```

## Components

### Deployment

Installs custom assets into a 3X-UI host.

- [Installer](https://github.com/xlordgrim/3x-sub/blob/main/install.sh): shell script · Installs or updates localized assets on AMD64 and ARM64 hosts. · `install.sh`
- [Uninstaller](https://github.com/xlordgrim/3x-sub/blob/main/uninstall.sh): shell script · Restores the default subscription experience. · `uninstall.sh`
- **System services**: systemd · Linux service integration supporting the panel installation.

### Installed frontend

Subscription page assets served by the host panel.

- [Subscription subpage](https://github.com/xlordgrim/3x-sub/blob/main/web/html/settings/panel/subscription/subpage.html): HTML page · Panel-integrated subscription UI document. · `web/html/settings/panel/subscription/subpage.html`
- [Premium theme](https://github.com/xlordgrim/3x-sub/blob/main/web/assets/css/premium.css): CSS · Responsive dark/light visual system and transitions. · `web/assets/css/premium.css`
- [Subscription controller](https://github.com/xlordgrim/3x-sub/blob/main/web/assets/js/subscription.js): browser JavaScript · Renders subscription state, QR codes, notifications, themes, and telemetry. · `web/assets/js/subscription.js`
- **Subscriber browser**: browser client · Displays links, QR codes, quota/status, and live server metrics.

### 3X-UI host runtime

Owns routing, sessions, and subscription/monitoring APIs.

- **3X-UI panel**: host application · Serves the page and provides panel context, routing, and authentication.
- **Subscription & monitoring endpoints**: host APIs · Authenticated host-provided subscription and live server data.

### Repository delivery

Build and public demo materials.

- [Custom panel build](https://github.com/xlordgrim/3x-sub/blob/main/.github/workflows/build-custom-xui.yml): GitHub Actions workflow · Builds the custom panel delivery artifact. · `.github/workflows/build-custom-xui.yml`
- [Demo page](https://github.com/xlordgrim/3x-sub/blob/main/test.html): HTML entry point · Browser-accessible demonstration entry point outside the installed panel path. · `test.html`
- [Screenshots](https://github.com/xlordgrim/3x-sub/tree/main/screenshots): static assets · Documentation and public demo imagery. · `screenshots`
- **GitHub Pages demo**: static hosting · Externally hosted public demonstration surface.

## Connections

- Installer → 3X-UI panel: deploys assets to
- Uninstaller → 3X-UI panel: restores default page
- System services → 3X-UI panel: manages runtime
- Installer → Subscription subpage: places
- Installer → Premium theme: places
- Installer → Subscription controller: places
- 3X-UI panel → Subscription subpage: serves
- Subscription subpage → Premium theme: loads
- Subscription subpage → Subscription controller: loads
- Subscriber browser → 3X-UI panel: opens subscription page
- Subscription controller → Subscription & monitoring endpoints: reads and polls
- Subscription & monitoring endpoints → Subscription controller: subscription and telemetry
- Subscription controller → Subscriber browser: updates UI
- Custom panel build → Installer: delivers release assets
- Demo page → GitHub Pages demo: published as
- Screenshots → GitHub Pages demo: supports demo/docs