# laisky/one-api architecture

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

- Interactive diagram: https://gitdiagram.com/laisky/one-api
- Repository: https://github.com/laisky/one-api

## Overview

##### Main Components
- API Server / Core Backend: This comprises the main entry point (main.go), the router (in the “router” directory), controllers (in “controller” and “relay/controller”), middleware (in “middleware”), and models (in “model” and supporting directories). This layer handles HTTP requests, processes authentication, logging, caching, rate-limiting, and dispatches business logic.
- External Integration / Relay Adaptors: The “relay” folder is extensive and contains adaptors for various providers (openai, aws, anthropic, tencent, etc.). Represent them as separate blocks connected to the core backend to show how API calls are forwarded to and received from different external AI providers.
- Web Frontend: Multiple web subdirectories (for example “web/air”, “web/berry”, “web/default”) indicate a separate full-stack front-end interface. Represent this as the “Web/Dashboard UI” that interacts with the backend via HTTP/API calls.
- Database and Cache: Look for files like common/database.go and Redis configuration hints in the README (environment variable REDIS_CONN_STRING). Add “Database” (persistent storage for user data, tokens, logs, etc.) and “Cache/Redis” as auxiliary components.
- Monitoring & Logging: The “monitor” directory and extensive logging functionality (in common/logger) suggest dedicated modules for system monitoring and metrics.

##### Relationships and Data Flow
- Client Interaction: Show user devices (or external clients) connecting to the Web Frontend and the API Server.
- HTTP Request Flow: Illustrate that incoming HTTP/API requests first hit the router, which then passes them through middleware (for authentication, CORS, rate limiting, etc.) before reaching the controllers.
- Business Logic: Controllers use services from the “common” layer and access models for business data. Label them to show how they trigger operations such as updating quota, billing, or token management.
- Data Storage & Cache: The controllers and middleware interact with persistent storage (database) and caching systems (Redis) for session management, user data, and other critical state information.

##### Architectural Patterns & Design Principles
- Layered Architecture: Clearly separate the presentation layer (web frontends), the API layer (routers, controllers, middleware), and the integration/business logic layers (models, relay adaptors, common utilities).
- Separation of Concerns: Each directory (for example, “controller”, “middleware”, “model”, “common”) represents a distinct responsibility. This should be visualized in separate blocks or tiers.
- Extensibility: The extensive relay/adaptor folder suggests a plug-in style design where new external service integrations can be added without affecting the core. Emphasize this loosely coupled integration.
- Use of External Configuration: Configuration-related files (e.g., .env.example, Dockerfile, docker-compose.yml, Makefile) show that the system is designed for flexible deployment and containerization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client("User Clients"):::client
    WebUI("Web/Dashboard UI"):::frontend

    subgraph "API Server"
        Entry("Main.go (Entry)"):::server
        Router("Router"):::server
        Middleware("Middleware"):::server
        Controllers("Controllers"):::server
        Models("Models"):::server
        Common("Common Services & Utilities"):::utilities
    end

    Relay("Relay Adaptors"):::integration
    External[/"External AI Services"/]:::external
    DB(("Database")):::db
    Cache(("Redis Cache")):::cache
    Logging("Logging"):::monitor
    Monitoring("Monitoring"):::monitor

    Client -->|"access"| WebUI
    WebUI -->|"API_call"| Entry
    Client -->|"send_request"| Entry
    Entry -->|"routes"| Router
    Router -->|"processes"| Middleware
    Middleware -->|"calls"| Controllers
    Controllers -->|"queries"| Models
    Controllers -->|"uses"| Common
    Controllers -->|"forwards"| Relay
    Relay -->|"APICall"| External
    Common -->|"db_access"| DB
    Common -->|"cache_access"| Cache
    Controllers -->|"db_access"| DB
    Controllers -->|"cache_access"| Cache
    Common -->|"logs_to"| Logging
    Common -->|"monitors"| Monitoring

    click Entry "https://github.com/laisky/one-api/blob/main/main.go"
    click Router "https://github.com/laisky/one-api/tree/main/router"
    click Middleware "https://github.com/laisky/one-api/tree/main/middleware"
    click Controllers "https://github.com/laisky/one-api/tree/main/controller"
    click Models "https://github.com/laisky/one-api/tree/main/model"
    click Common "https://github.com/laisky/one-api/tree/main/common"
    click Relay "https://github.com/laisky/one-api/tree/main/relay"
    click WebUI "https://github.com/laisky/one-api/tree/main/web"
    click DB "https://github.com/laisky/one-api/blob/main/common/database.go"
    click Cache "https://github.com/laisky/one-api/blob/main/common/redis.go"
    click Logging "https://github.com/laisky/one-api/blob/main/common/logger/logger.go"
    click Monitoring "https://github.com/laisky/one-api/tree/main/monitor"

    classDef client fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef frontend fill:#fbb,stroke:#333,stroke-width:2px;
    classDef server fill:#bbf,stroke:#333,stroke-width:2px;
    classDef utilities fill:#cfc,stroke:#333,stroke-width:2px;
    classDef integration fill:#fc9,stroke:#333,stroke-width:2px;
    classDef external fill:#ff9,stroke:#333,stroke-width:2px;
    classDef db fill:#faa,stroke:#333,stroke-width:2px;
    classDef cache fill:#afa,stroke:#333,stroke-width:2px;
    classDef monitor fill:#eef,stroke:#333,stroke-width:2px;
```
