# martialbe/one-hub architecture

> Architecture diagram of the GitHub repository martialbe/one-hub, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/martialbe/one-hub
- Repository: https://github.com/martialbe/one-hub

## Overview

##### Project Type & Purpose
- This is a full-stack application with a Go-based backend and a React-based frontend (located in the “web” directory). The backend is a monolith organized using a layered (MVC-inspired) architecture. It is built for interfacing with multiple third-party AI service providers (chat, image, speech, payment, etc.) and incorporates extended functionalities such as user dashboards, notifications, metrics, scheduling, and integrations with payment gateways.
- The README tells us the project is a customized “one-api” with significant enhancements—supporting features such as dynamic model lists, supplier integrations, Telegram bot support, and Prometheus metrics—aimed at providing a unified hub for AI model services.

##### Analyzing the File Structure – Key Directories
- Backend Core:
- “common”: Contains shared utilities, configuration modules, database connections, caching, cryptography, logging, notifications, rate-limiters, scheduler, and integrations (e.g., OIDC, redis, requester, image processing, etc.).
- “controller”: Implements the business logic endpoints (e.g., analytics, billing, channel operations, order/payment, token management, user/group handling) by interfacing with the lower-level common libraries.
- “middleware”: Houses cross-cutting concerns such as authentication, logging, CORS, API rate limiting, request tracing, metrics, etc.
- “model”: Defines domain objects and data schema (e.g., channel, user, pricing, order), indicating an MVC-like pattern.
- “router”: Sets up API, dashboard, relay, and web routes for request distribution.
- “cron”: Contains scheduled tasks (jobs) that likely perform background updates or maintenance.
- “cli”: Provides command-line interfaces (export, flag parsing) to run administrative tasks.
- “payment” & “providers”: These directories implement integrations. “payment” encapsulates various payment gateways (e.g., Alipay, Stripe, wxpay) while “providers” aggregates integration with various third-party AI vendors (OpenAI, Azure, Anthropic, etc.).
- “relay”: Provides a layer for proxying or aggregating responses from providers; it includes modules for chat, completions, image processing, and even support for tasks.
- Frontend:
- “web”: A React project that contains UI components, state management, routes, themes, and assets to deliver a rich user and admin dashboard.
- Deployment & Integration:
- Files like Dockerfile(s), docker-compose.yml, Taskfile.yml, GitHub workflows, and configuration samples (config.example.yaml) suggest containerized deployment and CI/CD integration.

a. Main Components:
- External Clients: Web browsers, Telegram bots, API consumers.
- Frontend (React-based application in “web”).
- API Gateway / Router (exposed via “router” components) which handles incoming HTTP(S) requests.
- Controllers & Middleware – the layer where API request validation, authentication, logging, caching, and rate limiting are applied.
- Core Business Logic / Service Layer – built from “common” utilities, “model” data objects, and “controller” endpoints.
- Integration Modules:
- Payment Module (with distinct gateways under “payment”).
- Provider Integrations (all vendor-specific implementations under “providers”).
- Relay Layer (for additional proxy/aggregation logic).
- Background Processes: Cron jobs, CLI tools, and scheduler (in “cron”, “common/scheduler”, “metrics”).
- Data Stores & Cache:
- Database connectivity (as indicated in “common/database.go”).
- Redis (via “common/config/redis.go” and “common/redis”, for caching).
b. Relationships & Interactions:
- The API Gateway (router) passes requests through middleware (authentication, rate limiting, etc.) to Controllers.
- Controllers call upon common utilities and business logic (such as payment processing, notifications, and logging).
- Business logic integrates with external API providers (through the “providers” and “relay” layers)—each handled as a separate module.
- Scheduled tasks (Cron) are depicted as independent processes that interact with the business logic layer and database.
- The frontend communicates with the backend’s API endpoints while also handling client-side logic.
c. Architectural Patterns & Design Principles:
- Layered architecture/MVC pattern: Routing → Middleware → Controllers → Models/Service Layer.
- Modular design: Payment, Providers, and Relay modules are kept separated to ease integration with multiple external services.
- Separation of concerns: The project cleanly distinguishes between core utility functions (“common”), business logic (“controller”/”model”), and integration logic (“providers”, “payment”, “relay”).
d. Key Technologies, Frameworks, and Libraries:
- Go Language & Gin web framework (as suggested by “common/gin.go”).
- React (in the “web” directory) for the frontend.
- Docker for containerization.
- Prometheus (mentioned in README) for metrics.
- Redis and likely an SQL/NoSQL database (via “common/database.go”) for persistence.
- CI/CD pipelines via GitHub Actions (“.github/workflows”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients and Frontend
    subgraph "External Layer"
        EC["External Clients"]:::external
        FE["Frontend UI (React)"]:::frontend
    end

    %% Backend Core Layers
    subgraph "Backend Layer"
        RG["API Gateway/Router"]:::backend
        MW["Middleware (Auth, RateLimit, etc.)"]:::backend
        CT["Controllers (Business Logic Endpoints)"]:::backend
        BL["Core Utilities & Service Layer"]:::backend
        DM["Domain Models"]:::backend
    end

    %% Integration Modules
    subgraph "Integration Modules"
        PM["Payment Module"]:::integration
        PI["Provider Integrations"]:::integration
        RL["Relay Layer"]:::integration
    end

    %% Background Processes and Tools
    subgraph "Background Processes & Tools"
        CR["Cron Jobs"]:::background
        SCH["Scheduler Tasks"]:::background
        CLI["CLI Tools"]:::background
        DB["Database Connection"]:::background
        RC["Redis Cache"]:::background
    end

    %% Deployment & CI/CD
    subgraph "Deployment & CI/CD"
        DEP["Deployment & CI/CD Configurations"]:::deployment
    end

    %% Connections for External Layer
    EC -->|"HTTP Requests"| RG
    EC -->|"Web Access"| FE

    %% Connections in Backend Layer
    RG -->|"passes request"| MW
    MW -->|"delegates to"| CT
    CT -->|"invokes"| BL
    BL -->|"manages"| DM

    %% Controller calls integration modules
    CT -->|"integration"| PM
    CT -->|"integration"| PI
    CT -->|"integration"| RL

    %% Background processes interactions
    CR -->|"triggers updates"| BL
    SCH -->|"schedules tasks"| BL
    CLI -->|"executes functions"| BL

    %% Business logic interactions with data
    BL -->|"reads/writes"| DB
    BL -->|"caches"| RC

    %% Class definitions for colour coding
    classDef external fill:#ffccff,stroke:#990099,stroke-width:2px;
    classDef frontend fill:#ccffff,stroke:#009999,stroke-width:2px;
    classDef backend fill:#ccffcc,stroke:#339933,stroke-width:2px;
    classDef integration fill:#ffccff,stroke:#cc66cc,stroke-width:2px;
    classDef background fill:#cce5ff,stroke:#3366cc,stroke-width:2px;
    classDef deployment fill:#ffffcc,stroke:#999900,stroke-width:2px;

    %% Click Events for Component Mappings
    click FE "https://github.com/martialbe/one-hub/tree/main/web/"
    click RG "https://github.com/martialbe/one-hub/tree/main/router/"
    click CT "https://github.com/martialbe/one-hub/tree/main/controller/"
    click MW "https://github.com/martialbe/one-hub/tree/main/middleware/"
    click BL "https://github.com/martialbe/one-hub/tree/main/common/"
    click DM "https://github.com/martialbe/one-hub/tree/main/model/"
    click PM "https://github.com/martialbe/one-hub/tree/main/payment/"
    click PI "https://github.com/martialbe/one-hub/tree/main/providers/"
    click RL "https://github.com/martialbe/one-hub/tree/main/relay/"
    click CR "https://github.com/martialbe/one-hub/blob/main/cron/main.go"
    click SCH "https://github.com/martialbe/one-hub/blob/main/common/scheduler/main.go"
    click CLI "https://github.com/martialbe/one-hub/tree/main/cli/"
    click DB "https://github.com/martialbe/one-hub/blob/main/common/database.go"
    click RC "https://github.com/martialbe/one-hub/blob/main/common/config/redis.go"
    click DEP "https://github.com/martialbe/one-hub/blob/main/docker-compose.yml"
```
