# calcium-ion/new-api architecture

> Architecture diagram of the GitHub repository calcium-ion/new-api, 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/calcium-ion/new-api
- Repository: https://github.com/calcium-ion/new-api

## Overview

##### Project Type & Purpose
- The README describes New API as a next-generation AI model gateway and asset management system. It integrates multiple AI models and third-party channels (OpenAI, Midjourney, Suno, among others), includes capabilities such as online payment, token management, caching, and support for various authentication methods.
- It is a full-stack application built with a Go backend and a modern JavaScript/React-based frontend (see the “web” directory).

##### Analyzing the File Structure
- The backend is primarily in Go (files like main.go, common/, controller/, service/, middleware/, model/, dto/, and constant/). These directories indicate an MVC-like separation:
- “controller” handles HTTP requests and routes.
- “service” contains the business logic.
- “model” manages data and database interaction.
- “middleware” provides cross-cutting concerns (rate limiting, authentication, logging, etc.).
- “common” and “constant” share utilities and configuration constants.
- The “relay” directory is extensive. It encapsulates adapters and handlers for multiple external channels. This is a key part of the architecture dealing with external API integrations for AI models and services.
- The “web” directory contains all frontend components (React components, pages, routing, and styling) and assets, demonstrating a clear separation between client and server.
- Configuration files (Dockerfile, docker-compose.yml, .env.example, Makefile) and CI/CD workflows (.github/workflows) indicate containerized and continuous deployment practices.

##### Main Components & Interactions
a. Frontend (Web):
- Built with modern JavaScript/React (using Vite as seen in vite.config.js and package.json).
- Manages UI for users including dashboards, settings, and chat interfaces.
b. Backend API Server:
- Exposes RESTful endpoints for various functionalities (controllers provide endpoints for billing, tasks, user management, channel operations, etc.).
- Routes HTTP requests via the “router” modules.
- Utilizes middleware for aspects like authorization, rate limiting, logging, etc.
c. Data Persistence Layer:
- Supports local SQLite (in Docker deployments) or remote MySQL/PostgreSQL databases.
- The “model” and “common/database.go” files indicate structured access for CRUD operations.
d. Relay/Integration Layer:
- The “relay” directory contains adapters and handlers for multiple external AI channels (e.g., OpenAI, Midjourney, Suno, Claude, Dify, and various others).
- These modules manage the data transformation and API calls between the internal system and third-party services.
e. Caching & Rate Limiting:
- Redis integration is managed in common/redis.go and through middleware. Caching mechanisms and rate limiting settings are essential for performance (and are documented in the README).
f. External Services:
- Authentication providers (e.g., Telegram, LinuxDO, OIDC) and payment channels (e.g., via the billing controllers).
- Integration with third-party API services for AI model interactions.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    subgraph "Frontend"
        FE["Web UI (React)"]:::frontend
    end

    %% Backend API Server components
    subgraph "Backend API Server (Go)"
        CONT["Controller Layer"]:::backend
        SERV["Service Layer"]:::backend
        MED["Middleware"]:::backend
        RELAY["Relay Layer"]:::relay
    end

    %% Data Persistence Layer
    subgraph "Data Persistence"
        MODEL["Model (model/)"]:::database
        DB["DB Connector (common/database.go)"]:::database
    end

    %% Caching Layer
    subgraph "Caching"
        CACHE["Redis (Caching)"]:::redis
    end

    %% External AI & Integration Services
    subgraph "External Services"
        OPENAI["OpenAI"]:::external
        MIDJOURNEY["Midjourney"]:::external
        SUNO["Suno API"]:::external
        CLAUDE["Claude"]:::external
        OTHERS["Others"]:::external
    end

    %% External Providers (Authentication & Payment)
    subgraph "External Providers"
        AUTH["Auth Providers (OIDC,Telegram,LinuxDO)"]:::external
        BILLING["Payment System (Billing)"]:::external
    end

    %% Deployment / Containerization
    DEPLOY["Containerization (Docker & docker-compose)"]:::deployment

    %% Connections
    FE -->|"HTTPRequest"| CONT
    CONT -->|"calls"| SERV
    CONT -->|"auth"| AUTH
    CONT -->|"billing"| BILLING
    MED -->|"applies"| SERV

    SERV -->|"reads/writes"| MODEL
    MODEL -->|"via"| DB
    SERV -->|"integrates"| RELAY

    MED -->|"handles"| CACHE

    RELAY -->|"adapts"| OPENAI
    RELAY -->|"adapts"| MIDJOURNEY
    RELAY -->|"adapts"| SUNO
    RELAY -->|"adapts"| CLAUDE
    RELAY -->|"adapts"| OTHERS

    %% Deployment connections (indicating containerization)
    FE --> DEPLOY
    CONT --> DEPLOY
    SERV --> DEPLOY
    MED --> DEPLOY
    RELAY --> DEPLOY
    MODEL --> DEPLOY

    %% Class 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 redis fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef relay fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef deployment fill:#fefefe,stroke:#6f42c1,stroke-width:2px;

    %% Click Events
    click FE "https://github.com/calcium-ion/new-api/tree/main/web/"
    click CONT "https://github.com/calcium-ion/new-api/tree/main/controller/"
    click SERV "https://github.com/calcium-ion/new-api/tree/main/service/"
    click MED "https://github.com/calcium-ion/new-api/tree/main/middleware/"
    click MODEL "https://github.com/calcium-ion/new-api/tree/main/model/"
    click DB "https://github.com/calcium-ion/new-api/blob/main/common/database.go"
    click CACHE "https://github.com/calcium-ion/new-api/blob/main/common/redis.go"
    click RELAY "https://github.com/calcium-ion/new-api/tree/main/relay/"
```
