# iidamie/deepseek2api architecture

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

- Interactive diagram: https://gitdiagram.com/iidamie/deepseek2api
- Repository: https://github.com/iidamie/deepseek2api

## Overview

##### Project Type and Purpose
- DeepSeek2API is an open-source backend service that exposes an OpenAI-compatible chat and model-listing API (`/v1/chat/completions` and `/v1/models`) by reverse-engineering DeepSeek’s undocumented API.
- It’s implemented as a single Python application (app.py) using a web framework (likely FastAPI/UVicorn) and provides multiple deployment options: Docker, docker-compose, Vercel, or native Python.

##### High-Level Architecture
- Monolithic API service with clear separation of concerns:
a. HTTP/API layer
b. Account & key management
c. Tokenization & hashing utilities
d. External DeepSeek integration
e. Static content (welcome page)

##### Main Components
a. Client (REST or OpenAI-compatible SDK)
b. HTTP Server (Uvicorn/FastAPI)
- Serves JSON endpoints (`GET /v1/models`, `POST /v1/chat/completions`)
- Serves a welcome HTML template (`templates/welcome.html`)
c. Configuration Loader
- Loads `config.json` (API keys + DeepSeek account pool) at startup
d. Account Manager
- Manages a rotating pool of DeepSeek accounts and API keys to distribute requests and mitigate rate limits
e. Tokenizer & Hashing Utilities
- Loads `tokenizer.json` and `tokenizer_config.json` for token counting (usage statistics)
- Uses `sha3_wasm_bg.*.wasm` for cryptographic hashing or signing requests
f. DeepSeek Proxy Service
- Forwards client requests to DeepSeek official endpoints
- Handles streaming responses (chunked transfer) when `stream=true`
- Injects OpenAI-compatible response schema (choices, usage, etc.)
g. Deployment & Infrastructure
- Dockerfile + docker-compose.yml define containerized environment
- Optional Nginx reverse proxy for buffering optimizations
- Vercel configuration (`vercel.json`) for serverless deployment
h. CI/CD
- GitHub Actions workflows (`.github/workflows/*.yml`) for building and pushing Docker images

##### Component Interactions / Data Flow
- Client → HTTP Server / Uvicorn
- HTTP Server
- reads config & initializes Account Manager
- validates incoming request and headers (Authorization: Bearer)
- (optional) invokes Tokenizer for usage logging
- selects an account/API key via Account Manager
- constructs DeepSeek request (may include hashed signature via WASM module)
- opens HTTP/stream connection to DeepSeek
- streams chunks back to Client, re-wrapping into OpenAI schema
- (If deployed behind Nginx) Nginx sits between Client and Uvicorn, handling low-level TCP and buffering settings

##### Architectural Patterns & Principles
- Layered architecture: Controllers (API) → Services (Account & Proxy) → Utilities (Tokenizer & WASM)
- Configuration-driven: all credentials & settings in `config.json`
- Single‐responsibility: each module (account manager, proxy, tokenizer) handles a distinct concern
- Streaming support: chunked transfer encoding for low-latency partial outputs
- Containerization: Docker best practices for isolation and reproducibility

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client (REST/OpenAI SDK)"]:::client
    Client -->|"HTTP JSON"| Nginx["Nginx Reverse Proxy"]:::external
    Nginx -->|"buffered TCP"| API

    subgraph "API / Web Layer"
        API["HTTP Server / API Layer\n(Uvicorn/FastAPI)"]:::api
        Welcome["Welcome HTML Template"]:::web
        ConfigLoader["config.json"]:::config
        API -->|"serves HTML"| Welcome
        API -->|"reads config"| ConfigLoader
    end

    subgraph "Business Logic"
        AccountManager["Account & Key Manager"]:::service
        ProxyService["DeepSeek Proxy Service"]:::service
        API -->|"select account"| AccountManager
        API -->|"forward request"| ProxyService
    end

    subgraph "Utilities"
        TokenizerJSON["tokenizer.json"]:::utility
        TokenizerConfig["tokenizer_config.json"]:::utility
        WASM["WASM Hash Module"]:::utility
        API -->|"token count"| TokenizerJSON
        API -->|"token config"| TokenizerConfig
        API -->|"hash/sign"| WASM
    end

    ProxyService -->|"HTTP JSON / chunked"| DeepSeekAPI["DeepSeek Official API"]:::external
    DeepSeekAPI -->|"chunked stream"| ProxyService
    ProxyService -->|"OpenAI-compatible JSON"| API
    API -->|"HTTP JSON"| Client

    subgraph "Deployment & Infrastructure"
        DockerfileNode["Dockerfile"]:::infra
        Compose["docker-compose.yml"]:::infra
        VercelCfg["vercel.json"]:::infra
        Requirements["requirements.txt"]:::infra
        DockerIgnore[".dockerignore"]:::infra
        GitIgnore[".gitignore"]:::infra
        VersionInfo["version.txt"]:::infra
        CI1[".github/workflows/docker-image-dev.yml"]:::infra
        CI2[".github/workflows/docker-image.yml"]:::infra
        CI3[".github/workflows/sync.yml"]:::infra

        DockerfileNode -->|"defines container"| API
        Compose -->|"orchestrates"| DockerfileNode
        VercelCfg -->|"serverless deploy"| API
        CI1 -->|"build/push image"| DockerfileNode
        CI2 -->|"build/push image"| DockerfileNode
        CI3 -->|"sync repos"| DockerfileNode
    end

    classDef client fill:#D0E8FF,stroke:#0066CC,stroke-width:1px
    classDef api fill:#CFE2FF,stroke:#0044AA,stroke-width:1px
    classDef service fill:#DFF2E1,stroke:#2E8B57,stroke-width:1px
    classDef utility fill:#FFE4B5,stroke:#FF8C00,stroke-width:1px
    classDef config fill:#F5F5F5,stroke:#999999,stroke-width:1px,stroke-dasharray: 5 5
    classDef web fill:#FFF2CC,stroke:#D79B00,stroke-width:1px
    classDef external fill:#EDEDED,stroke:#888888,stroke-width:1px,stroke-dasharray: 3 3
    classDef infra fill:#F0F0F0,stroke:#666666,stroke-width:1px

    click API "https://github.com/iidamie/deepseek2api/blob/main/app.py"
    click Welcome "https://github.com/iidamie/deepseek2api/blob/main/templates/welcome.html"
    click ConfigLoader "https://github.com/iidamie/deepseek2api/blob/main/config.json"
    click AccountManager "https://github.com/iidamie/deepseek2api/blob/main/app.py"
    click TokenizerJSON "https://github.com/iidamie/deepseek2api/blob/main/tokenizer.json"
    click TokenizerConfig "https://github.com/iidamie/deepseek2api/blob/main/tokenizer_config.json"
    click WASM "https://github.com/iidamie/deepseek2api/blob/main/sha3_wasm_bg.7b9ca65ddd.wasm"
    click ProxyService "https://github.com/iidamie/deepseek2api/blob/main/app.py"
    click DockerfileNode "https://github.com/iidamie/deepseek2api/tree/main/Dockerfile"
    click Compose "https://github.com/iidamie/deepseek2api/blob/main/docker-compose.yml"
    click VercelCfg "https://github.com/iidamie/deepseek2api/blob/main/vercel.json"
    click Requirements "https://github.com/iidamie/deepseek2api/blob/main/requirements.txt"
    click DockerIgnore "https://github.com/iidamie/deepseek2api/blob/main/.dockerignore"
    click GitIgnore "https://github.com/iidamie/deepseek2api/blob/main/.gitignore"
    click VersionInfo "https://github.com/iidamie/deepseek2api/blob/main/version.txt"
    click CI1 "https://github.com/iidamie/deepseek2api/blob/main/.github/workflows/docker-image-dev.yml"
    click CI2 "https://github.com/iidamie/deepseek2api/blob/main/.github/workflows/docker-image.yml"
    click CI3 "https://github.com/iidamie/deepseek2api/blob/main/.github/workflows/sync.yml"
```
