# gozargah/marzban architecture

> Architecture diagram of the GitHub repository gozargah/marzban, 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/gozargah/marzban
- Repository: https://github.com/gozargah/marzban

## Overview

##### Main Components

- Frontend (Dashboard UI):
- The “app/dashboard” directory contains a complete React application built in TypeScript. This is the web user interface that administrators and users interact with.
- This component is responsible for rendering pages (login, dashboard, settings, etc.), displaying statistics, handling subscriptions, and even providing multi-language support.

- Backend (REST API & Business Logic):
- The core Python code resides in “main.py”, “app/routers”, “app/models”, “app/dependencies”, etc. This layer handles incoming API requests, authentication, business logic, and configuration management.
- Using FastAPI (implied by Uvicorn and the structure) or a similar ASGI framework, it exposes REST endpoints (including the built-in docs when enabled).

- Database and ORM Layer:
- The “app/db” directory holds the database initialization, CRUD functions, and migration scripts (through Alembic). It uses SQLAlchemy as the ORM.
- The configuration (through environment variables and .env files) supports SQLite, MySQL, or MariaDB.

- Xray Integration & Proxy Management:
- Marzban deeply integrates with Xray-core. The “xray_api” and “app/xray” directories include the integration logic and gRPC communication (via protobuf-generated code).
- This component transforms backend configurations into valid Xray configurations and handles complex multi-protocol proxy setups (e.g., Vmess, VLESS, Trojan, and Shadowsocks).

- External Service Integrations:
- Telegram Bot: “app/telegram” hosts Telegram integrations (with handlers for admins and users) for notifications and CLI operations.
- Discord: “app/discord” indicates further integrations, potentially for additional notification or logging.
- CLI and Automation: The “cli” folder and “marzban-cli.py” provide command-line tools for administration, user management, and other maintenance tasks.
- Backup Service: Although not a separate folder, the backup commands and scripts are integrated into the project, as described in the README.
- Marzban Node: Mentioned in the README, it represents a distributed service to handle multi-node infrastructure, which can also be noted on the overall design but might be drawn as an external (or sibling) component.

##### Relationships and Interactions

- The Frontend communicates with the Backend via REST API calls to retrieve data, monitor statistics, and perform administrative tasks.
- The Backend encapsulates business logic and interacts with:
- The Database (via SQLAlchemy and Alembic migrations) to store proxy user data, node configurations, and statistics.
- The Xray integration layer to generate configuration files and relay commands/data to the Xray-core binary.
- External integrations such as the Telegram and Discord bots to manage notifications, automation, and alerting.
- The CLI commands act as an alternate means for administrators to interact with the backend.
- Data flows directionally:
- User actions from the dashboard lead to API calls.
- The API, in turn, queries/upserts to the database and triggers actions in the Xray layer or notification systems.
- Scheduled jobs (in “app/jobs”) run in the background to review users, record usages, or send periodic notifications.

##### Important Architectural Patterns and Design Principles

- Layered Architecture:
- Clearly delineate UI, application logic, data access, and integration concerns.
- Microservice or Modular Components (Implicit):
- Extensibility & Integrations:
- The design makes use of adapters for external services (Telegram, CLI, Discord) and uses configuration-driven behavior (e.g., environment variables for SSL, database URL, Xray configuration path).

##### Specify Relevant Technologies and Frameworks

- Frontend: React with TypeScript (using Vite, as seen in “vite.config.ts”) and various UI components.
- Backend: Python (with possible FastAPI/ASGI framework), SQLAlchemy for ORM, and Alembic for migrations.
- Infrastructure: Docker (with Dockerfile, docker-compose.yml), systemctl integration scripts, and Nginx configuration examples provided in the README.
- Xray Integration: gRPC and protobuf (via the “xray_api/proto” folder) for managing communication with Xray-core.
- CLI & Jobs: Custom Python scripts for command-line interactions and scheduled jobs for task automation.

##### Specific Elements

- From Frontend to Backend (HTTP/REST API calls).
- From Backend to Database (CRUD operations).
- From Backend to Xray Integration (configuration commands/updates) and vice versa (status updates or logs).
- From Backend to External Notifications (Telegram/Discord).
- From CLI to Backend (command invocations).
- Rectangles for services (API, UI, Database, Xray-Core).

##### Final Advice

- Drill down into each tier to list specific modules (for example, in the backend, you have routers, models, and integrations with proxy management and notifications).
- How configuration and environment-based variables (from the .env and configuration files) guide many of these interactions.
- Don’t hesitate to include any critical external dependencies (like Xray-core) that affect system behavior.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        FE["Frontend Dashboard (React)"]
    end

    %% Application Layer (Backend)
    subgraph "Backend API Server (Python)"
        API_Core["API Core: main.py"]
        Routers["Routers: app/routers"]
        Models["Models: app/models"]
        Dependencies["Dependencies: app/dependencies"]
        CLI["CLI Tools"]
        CLI_CMD["CLI Command"]
        Jobs["Scheduled Jobs"]
        Subscription["Subscription Service"]
    end

    %% Persistence Layer
    DB["Database (SQLAlchemy + Alembic)"]

    %% Integration Layer (External Services)
    subgraph "Integration Layer"
        Xray["Xray Integration Module"]
        Xray_API["Xray API Module"]
        Telegram["Telegram Bot"]
        Discord["Discord Integration"]
    end

    %% External Node
    MN["Marzban Node"]

    %% Connections
    FE -->|"HTTP/REST"| API_Core

    API_Core -->|"routes"| Routers
    API_Core -->|"models"| Models
    API_Core -->|"dependencies"| Dependencies

    API_Core -->|"CRUD"| DB

    API_Core -->|"config_commands"| Xray
    API_Core -->|"grpc_calls"| Xray_API

    API_Core -->|"notify"| Telegram
    API_Core -->|"notify"| Discord

    CLI -->|"invoke_api"| API_Core
    CLI_CMD -->|"invoke_api"| API_Core

    Jobs -->|"periodic_tasks"| API_Core
    Jobs -->|"update_db"| DB

    API_Core -->|"subscription"| Subscription

    API_Core -->|"node_config"| MN
    MN -->|"status_update"| API_Core

    %% Click Events
    click FE "https://github.com/gozargah/marzban/tree/master/app/dashboard"
    click API_Core "https://github.com/gozargah/marzban/blob/master/main.py"
    click Routers "https://github.com/gozargah/marzban/tree/master/app/routers"
    click Models "https://github.com/gozargah/marzban/tree/master/app/models"
    click Dependencies "https://github.com/gozargah/marzban/tree/master/app/dependencies"
    click DB "https://github.com/gozargah/marzban/tree/master/app/db"
    click Xray "https://github.com/gozargah/marzban/tree/master/app/xray"
    click Xray_API "https://github.com/gozargah/marzban/tree/master/xray_api"
    click Telegram "https://github.com/gozargah/marzban/tree/master/app/telegram"
    click Discord "https://github.com/gozargah/marzban/tree/master/app/discord"
    click CLI "https://github.com/gozargah/marzban/tree/master/cli"
    click CLI_CMD "https://github.com/gozargah/marzban/blob/master/marzban-cli.py"
    click Jobs "https://github.com/gozargah/marzban/tree/master/app/jobs"
    click Subscription "https://github.com/gozargah/marzban/tree/master/app/subscription"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef database fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef integration fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;

    class FE frontend;
    class API_Core,Routers,Models,Dependencies,CLI,CLI_CMD,Jobs,Subscription backend;
    class DB database;
    class Xray,Xray_API,Telegram,Discord integration;
    class MN external;
```
