# sohaha/hub-api architecture

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

- Interactive diagram: https://gitdiagram.com/sohaha/hub-api
- Repository: https://github.com/sohaha/hub-api

## Overview

##### Project type and purpose
- This is a Go-based, monolithic backend HTTP service (“hub-api”) whose purpose is to sit in front of multiple large-language-model providers (e.g. OpenAI), perform load balancing, failover, model mapping, and expose a unified API for chat completions, model listing, and provider configuration.

##### File structure
- Top level:
- main.go – entry point
- Dockerfile, GitHub Actions workflows, GoReleaser config – build & deploy
- go.mod/go.sum – dependency management
- internal/
- app.go – application bootstrap (load config, start scheduler)
- router.go – HTTP router (mounts v1 and admin routes)
- controller/ – HTTP handlers (index.go, v1.go)
- errcode/ – centralized error codes & i18n
- module.go – module registration
- tasks.go – background tasks (health checks, cooldown resets)
- module/chat/
- chat_controller.go – business logic for chat endpoints
- parse.go/conf.go/provider_controller.go – request parsing, config APIs
- provider/openai/
- llm.go – OpenAI provider implementation
- json.go – JSON marshalling/unmarshalling
- Configuration files (config.toml, provider.json) are read at startup or updated via API.

##### Key insights from README
- Features: multiple LB algorithms, failover/silence, model mapping
- Usage: HTTP API, Docker container, systemd service
- Config: two layers (program config + per-provider JSON)
- Endpoints:
- POST /v1/chat/completions
- GET /v1/models
- GET/POST under /chat for provider management

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Clients["Clients\n(web/mobile/other)"]:::external

    %% Hub-API Service
    subgraph "Hub-API Service"
        direction TB

        EntryPoint["main.go"]:::service
        AppBootstrap["Application Bootstrap\n(internal/app.go)"]:::service
        HTTPServer["HTTP Server\n(net/http/Gin)"]:::service

        subgraph "Router Layer"
            Router["Router\n(internal/router.go)"]:::frontend
        end

        subgraph "Controller Layer"
            IndexCtrl["Index Controller\n(internal/controller/index.go)"]:::frontend
            V1Ctrl["V1 Controller\n(internal/controller/v1.go)"]:::frontend
        end

        subgraph "Service Layer"
            ChatService["Chat Service\n(module/chat)"]:::service
            LoadBalancer["Load Balancer\n(round-robin, weights)"]:::service
            ModuleReg["Module Registration\n(internal/module.go)"]:::service
            ErrCodeCode["Error Codes\n(internal/errcode/code.go)"]:::service
            ErrCodeI18n["Localization\n(internal/errcode/i18n.go)"]:::service
            ErrCodeUtils["Errcode Utils\n(internal/errcode/utils.go)"]:::service
        end

        subgraph "Provider Manager"
            ProviderMgr["Provider Manager\n(interface registry)"]:::service
            OpenAILLM["OpenAI Provider\n(provider/openai/llm.go)"]:::service
            JSONMarshal["JSON Marshalling\n(provider/openai/json.go)"]:::service
        end

        subgraph "Config Store"
            ConfigFiles["Config Store\n(config.toml + provider.json)"]:::config
        end

        subgraph "Scheduler / Tasks"
            Scheduler["Scheduler\n(internal/tasks.go)"]:::service
        end
    end

    %% External Services
    ExternalLLM["OpenAI API\n(External LLM)"]:::external

    %% Build & Deployment
    subgraph "Build & Deployment"
        Dockerfile["Dockerfile"]:::service
        Goreleaser[".goreleaser.yml"]:::service
        GH_Docker[".github/workflows/docker.yml"]:::service
        GH_Release[".github/workflows/release.yml"]:::service
    end

    %% Dependency Management
    subgraph "Dependencies"
        GoMod["go.mod"]:::service
        GoSum["go.sum"]:::service
    end

    %% Relationships
    Clients -->|HTTP/HTTPS| HTTPServer
    HTTPServer -->|routes| Router
    Router -->|calls| IndexCtrl
    Router -->|calls| V1Ctrl
    IndexCtrl -->|invoke| ChatService
    V1Ctrl -->|invoke| ChatService
    ChatService -->|select| LoadBalancer
    LoadBalancer -->|choose provider| ProviderMgr
    ProviderMgr -->|use| OpenAILLM
    OpenAILLM -->|calls| ExternalLLM
    ExternalLLM -->|response JSON| OpenAILLM
    OpenAILLM -->|return| ProviderMgr
    ProviderMgr -->|return| ChatService
    ChatService -->|response| V1Ctrl
    V1Ctrl -->|HTTP 200 JSON| Clients

    %% Admin flow
    Router -->|POST /chat/provider| ProviderMgr
    ProviderMgr -->|update| ConfigFiles
    ConfigFiles -->|persist| ConfigFiles

    %% Scheduler tasks
    Scheduler -.->|health checks| ProviderMgr
    Scheduler -.->|cooldown reset| ProviderMgr

    AppBootstrap -->|load config| ConfigFiles
    AppBootstrap --> Scheduler
    EntryPoint --> AppBootstrap
    AppBootstrap --> HTTPServer
    AppBootstrap --> ModuleReg

    %% Build & Dependency links
    EntryPoint --> Dockerfile
    EntryPoint --> Goreleaser
    EntryPoint --> GH_Docker
    EntryPoint --> GH_Release
    EntryPoint --> GoMod
    EntryPoint --> GoSum

    %% Click Events
    click EntryPoint "https://github.com/sohaha/hub-api/blob/master/main.go"
    click AppBootstrap "https://github.com/sohaha/hub-api/blob/master/internal/app.go"
    click Router "https://github.com/sohaha/hub-api/blob/master/internal/router.go"
    click IndexCtrl "https://github.com/sohaha/hub-api/blob/master/internal/controller/index.go"
    click V1Ctrl "https://github.com/sohaha/hub-api/blob/master/internal/controller/v1.go"
    click ErrCodeCode "https://github.com/sohaha/hub-api/blob/master/internal/errcode/code.go"
    click ErrCodeI18n "https://github.com/sohaha/hub-api/blob/master/internal/errcode/i18n.go"
    click ErrCodeUtils "https://github.com/sohaha/hub-api/blob/master/internal/errcode/utils.go"
    click ModuleReg "https://github.com/sohaha/hub-api/blob/master/internal/module.go"
    click Scheduler "https://github.com/sohaha/hub-api/blob/master/internal/tasks.go"
    click ChatService "https://github.com/sohaha/hub-api/blob/master/module/chat/module.go"
    click OpenAILLM "https://github.com/sohaha/hub-api/blob/master/provider/openai/llm.go"
    click JSONMarshal "https://github.com/sohaha/hub-api/blob/master/provider/openai/json.go"
    click Dockerfile "https://github.com/sohaha/hub-api/tree/master/Dockerfile"
    click Goreleaser "https://github.com/sohaha/hub-api/blob/master/.goreleaser.yml"
    click GH_Docker "https://github.com/sohaha/hub-api/blob/master/.github/workflows/docker.yml"
    click GH_Release "https://github.com/sohaha/hub-api/blob/master/.github/workflows/release.yml"
    click GoMod "https://github.com/sohaha/hub-api/blob/master/go.mod"
    click GoSum "https://github.com/sohaha/hub-api/blob/master/go.sum"

    %% Styles
    classDef frontend fill:#D6E8FF,stroke:#000,stroke-width:1px
    classDef service fill:#CFF5D5,stroke:#000,stroke-width:1px
    classDef config fill:#FFEDC5,stroke:#000,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#000,stroke-width:1px
```
