# alireza0/s-ui architecture

> Architecture diagram of the GitHub repository alireza0/s-ui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alireza0/s-ui
- Repository: https://github.com/alireza0/s-ui

## Overview

##### Project Type and Purpose
- It includes both web frontend and backend components along with API interfaces for traffic routing, configuration, and status monitoring. Additionally, features like subscription services and scheduled jobs make this software multi-faceted.

##### File Structure
- Top-level directories such as "api", "app", "cmd", "config", "core", "cronjob", "database", "frontend", "logger", "middleware", "network", "service", "sub", "util", and "web" indicate modular segregation.
- The "api" directory contains HTTP API handlers (e.g., apiHandler.go, apiV2Handler.go) used for external and client requests.
- The "app", "cmd", and "core" directories appear to hold the main service startup logic, command-line tool operations (like migration scripts), and the primary backend business logic.
- "cronjob" sets up scheduled/periodic tasks, likely for system or status monitoring.
- "database" holds database initialization and model definitions (for endpoints, inbounds, outbounds, etc.) for persistence.
- The "frontend" directory is meant to be built and then integrated into the backend’s “web/html” folder, thus coupling the static content with backend serving.
- Other modules (“service”, “middleware”, “network”, “logger”) handle domain-specific business logic, validation, network connection management, and logging.
- Files like Dockerfile, docker-compose.yml, systemd service files, and various shell scripts indicate multiple deployment methods (manual, Docker, systemd).

##### README for Additional Insights
- The README highlights key features: multi-protocol support, API interface, advanced traffic routing, subscription services, and seamless integration between client management and system status.
- It includes instructions for both containerized (Docker) and manual installations, indicating that the system should be visible as a layered service (fronted by a web server, configured by APIs, and backed by persistent storage and network components).

a. Main Components
- Frontend: The web UI, compiled from the "frontend" directory, deployed into the "web" directory (serving static HTML, CSS, JS).
- API Layer: Located in the "api" directory; this layer receives RESTful calls and translates them into backend operations.
- Core Business Logic: Found under "core", "app", and "cmd" – handles request processing, routing logic, and core protocol configurations.
- Services: In the "service" directory, individual business services (client, endpoints, settings, TLS, etc.) manage specific functions.
- Database Layer: Under "database" with model definitions and backup routines; responsible for persistence of configurations, endpoints, and traffic statistics.
- Cron Jobs: The "cronjob" directory schedules periodic jobs (e.g., cleaning stats, checking core services).
- Middleware: Basic validations and request processing components.
- Network Components: The "network" directory for auto-HTTPS and listener setup.
- Subscription Module: The "sub" directory handles subscription services (link, JSON-based provisioning) for client configurations.
- Infrastructure Components: Logger (logging via "logger"), configuration system ("config"), and utilities ("util").

b. Relationships and Interactions
- The Frontend sends HTTP requests to the API layer.
- The API layer routes these requests to the Core/Service components.
- The Core components and Services access the Database to store/retrieve configuration and status data.
- Middleware (e.g., domainValidator) intercepts API calls to enforce validations.
- Cron jobs perform scheduled tasks that update or clean data in the Database or affect the Core.
- Network components work in tandem with the Core for establishing secure connections (auto HTTPS functionalities).
- The Subscription Module interacts with the Core and Database to generate and serve subscription information to clients.

c. Architectural Patterns and Design Principles
- Separation of concerns: clearly isolated directories for API, business logic, services, and infrastructure.
- Modular design: individual components (e.g., migration, logging, network utilities) for clarity and maintainability.
- Integration via APIs: decoupled frontend and backend through REST interfaces.
- Containerization readiness: Presence of Docker/Docker Compose files for environment consistency and deployment flexibility.

d. Relevant Technologies and Frameworks
- Written in Go, making use of Go’s modular structure.
- Systemd service files for deployment on Linux-based systems.
- Docker for containerized deployments.
- Likely usage of standard Go libraries for HTTP handling, logging, and database operations.

##### Elements
- Clear labels for each module/component:
- “Frontend (Web UI)” connected to “API Layer”.
- “API Layer” connecting to “Core Business Logic” and “Service Modules”.
- “Core” interfacing with “Database” and “Cron Jobs”.
- “Network Modules” as supporting components for secure connections.
- “Subscription Service” as part of the business logic.
- HTTP request/response flows between Frontend and API.
- Data flows from API to Core, and then to Database.
- Interaction flows from Cron jobs to update or query Core/Database.
- Distinguish components using:
- Annotations to note key functions (e.g., “API Handler”, “Log Management”, “Configuration”, “Validation Middleware”).
- Infrastructure elements such as Docker, systemd, and build/deployment scripts (Dockerfile, docker-compose.yml, install.sh) as peripheral modules that affect deployment rather than runtime architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User("User Browser"):::client

    subgraph "Frontend Layer"
        F1("Frontend Build"):::frontend
        F2("Frontend Deployment"):::frontend
    end

    User -->|"sends_HTTP_requests"| F1
    User -->|"sends_HTTP_requests"| F2
    F1 --- F2

    F1 & F2 -->|"calls_API"| API("API Layer"):::api

    API -->|"routed_by"| MW("Middleware (Validation)"):::middleware
    MW -->|"processes"| C("Core Business BusinessLogic"):::core
    MW -->|"init_start"| S("Application Startup & Cmd"):::startup
    S -->|"bootstraps"| C

    C -->|"invokes"| Service("Service Modules"):::service
    Service -->|"queries_stores"| DB("Database Layer"):::database

    C -->|"secures"| Net("Network Components"):::network

    C -->|"generates"| Sub("Subscription Module"):::subscription
    Sub -->|"fetches"| DB

    Cron("Cron Jobs"):::cron
    Cron -->|"updates"| DB
    Cron -->|"triggers"| C

    subgraph "Infrastructure"
        L("Logging"):::infrastructure
        Conf("Configuration"):::infrastructure
        U("Utilities"):::infrastructure
    end
    L -->|"supports"| C
    Conf -->|"supports"| C
    U -->|"supports"| C

    %% Click Events
    click F1 "https://github.com/alireza0/s-ui/tree/main/frontend/"
    click F2 "https://github.com/alireza0/s-ui/blob/main/web/web.go"
    click API "https://github.com/alireza0/s-ui/tree/main/api/"
    click C "https://github.com/alireza0/s-ui/tree/main/core/"
    click S "https://github.com/alireza0/s-ui/blob/main/app/app.go"
    click S "https://github.com/alireza0/s-ui/tree/main/cmd/"
    click Service "https://github.com/alireza0/s-ui/tree/main/service/"
    click DB "https://github.com/alireza0/s-ui/tree/main/database/"
    click Cron "https://github.com/alireza0/s-ui/tree/main/cronjob/"
    click MW "https://github.com/alireza0/s-ui/tree/main/middleware/"
    click Net "https://github.com/alireza0/s-ui/tree/main/network/"
    click Sub "https://github.com/alireza0/s-ui/tree/main/sub/"
    click L "https://github.com/alireza0/s-ui/tree/main/logger/"
    click Conf "https://github.com/alireza0/s-ui/tree/main/config/"
    click U "https://github.com/alireza0/s-ui/tree/main/util/"

    %% Styles
    classDef client fill:#f9d,stroke:#333,stroke-width:2px;
    classDef frontend fill:#cce,stroke:#333,stroke-width:2px;
    classDef api fill:#ccf,stroke:#333,stroke-width:2px;
    classDef middleware fill:#cfc,stroke:#333,stroke-width:2px;
    classDef core fill:#fcf,stroke:#333,stroke-width:2px;
    classDef startup fill:#ffc,stroke:#333,stroke-width:2px;
    classDef service fill:#cff,stroke:#333,stroke-width:2px;
    classDef database fill:#eef,stroke:#333,stroke-width:2px;
    classDef cron fill:#fee,stroke:#333,stroke-width:2px;
    classDef network fill:#efe,stroke:#333,stroke-width:2px;
    classDef subscription fill:#ffe,stroke:#333,stroke-width:2px;
    classDef infrastructure fill:#ddd,stroke:#333,stroke-width:2px;
```
