How gozargah/marzban works
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.