# easychen/openai-api-proxy architecture

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

- Interactive diagram: https://gitdiagram.com/easychen/openai-api-proxy
- Repository: https://github.com/easychen/openai-api-proxy

## Overview

##### Project type and purpose
- From the file tree and README, this is a lightweight, server-side OpenAI API proxy written in Node.js.
- It’s meant to be deployed in Docker or as a cloud function. It exposes OpenAI-compatible endpoints, adds optional Tencent Cloud text moderation, and supports Server-Sent Events (SSE) streaming.

##### File structure
- Top level:
- app.js – main Node.js entry point
- package.json – Node dependencies and scripts
- FUNC.md – Tencent Cloud Function deployment guide
- docker/ – a self-contained Docker build context (Dockerfile, its own app.js, fetchsse.js, package.json)
- README.md, README.CN.md – usage docs
- The separation of docker/ shows two deployment contexts: “bare-metal” Node.js or containerized.

##### README for additional insights
- Features: SSE streaming, text moderation via Tencent Cloud, PROXY_KEY auth.
- Environment variables configure port, proxy key, timeouts, Tencent credentials, region.
- API usage: acts as an HTTP GET/POST proxy, replacing the OpenAI base URL.
- Client integration: works with chatgpt-API library by overriding apiBaseUrl.

- Client applications (e.g., chatgpt library, custom frontends)
- OpenAI API Proxy (Node.js service)
- HTTP server (app.js)
- SSE handler (fetchsse.js)
- Moderation module (invokes Tencent Cloud Moderation)
- Auth middleware (PROXY_KEY validation)
- External services:
- OpenAI REST/SSE API endpoints
- Tencent Cloud Content Moderation API
- Deployment targets:
- Docker container
- Cloud Function runtime

b. Relationships & data flow:
1. Client sends request (HTTP GET/POST with optional stream parameter) →
2. Proxy’s auth middleware checks PROXY_KEY →
3. If moderation=true, Proxy calls Tencent Cloud Moderation API →
– If verdict = Block/High, abort or modify request
4. Proxy forwards sanitized request to OpenAI API (fetch-SSE for stream) →
5. OpenAI responds (streaming tokens or JSON payload) →
6. Proxy relays response to client via SSE or HTTP response

c. Architectural patterns & principles:
- Single-process event-driven server (Node.js)
- Middleware pipeline (auth → moderation → proxy)
- Separation of concerns: moderation logic isolated from streaming logic
- Config-driven deployment (env vars for keys, timeouts, ports)

d. Key technologies & libraries:
- Node.js 14+
- Express-style HTTP server (built into app.js)
- fetch-sse for streaming support
- Tencent Cloud SDK or direct HTTP calls for moderation
- Docker for containerization
- Optional: Cloud Function platform

##### Important details to capture
- Optional SSE path vs. standard HTTP path.
- Error handling: timeouts, moderation failures, streaming interruptions.
- How client must modify apiBaseUrl and key format (sk…:<PROXY_KEY>).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Applications"
        Client["Client Apps"]:::external
    end

    %% Proxy Service Layer
    subgraph "Proxy Service (Node.js)"
        Proxy["HTTP Server & Core Proxy Logic\n(env vars: PORT, PROXY_KEY, TIMEOUTS, TENCENT_* ...)"]:::internal
        Auth["Auth & Middleware Pipeline"]:::internal
        Mod["Moderation Module"]:::internal
        SSE["SSE Streaming Handler"]:::internal
    end

    %% External Services Layer
    subgraph "External Services"
        OA["OpenAI REST/SSE API"]:::external
        TC["Tencent Cloud Moderation API"]:::external
    end

    %% Deployment Options
    subgraph "Deployment Environments"
        Docker["Docker Container"]:::deploy
        DockerPkg["docker/package.json"]:::deploy
        CF["Cloud Function Runtime"]:::deploy
    end

    %% Project Files & Docs
    subgraph "Project Files"
        MainPkg["package.json"]:::docs
        Readme["README.md"]:::docs
        ReadmeCN["README.CN.md"]:::docs
        FuncGuide["FUNC.md"]:::docs
        License["LICENSE"]:::docs
        GitIgnore[".gitignore"]:::docs
    end

    %% Data Flows
    Client -->|"HTTP GET/POST"| Proxy
    Proxy -->|validate PROXY_KEY| Auth
    Auth -->|"if moderation=true"| Mod
    Mod -->|"Moderation Request (HTTP)"| TC
    TC -->|"Moderation Verdict"| Mod
    Mod -->|sanitized request| Proxy
    Proxy -->|"Standard HTTP"| OA
    Proxy -->|"SSE Stream"| SSE
    SSE -->|"Fetch-SSE"| OA
    OA -->|"Response/Stream"| Proxy
    Proxy -->|"Response/SSE"| Client

    %% Deployment Relationships
    Proxy -->|runs in| Docker
    SSE -->|bundled in| Docker
    Docker -->|uses| DockerPkg
    Proxy -->|deploy guide| CF

    %% Docs Relationships
    Proxy -->|deps & scripts| MainPkg
    Proxy -->|usage & config| Readme
    Proxy -->|中文文档| ReadmeCN
    CF -->|guide| FuncGuide
    Readme -->|license info| License
    Readme -->|ignore rules| GitIgnore

    %% Click Events
    click Proxy "https://github.com/easychen/openai-api-proxy/blob/master/app.js"
    click Auth "https://github.com/easychen/openai-api-proxy/blob/master/app.js"
    click Mod "https://github.com/easychen/openai-api-proxy/blob/master/app.js"
    click SSE "https://github.com/easychen/openai-api-proxy/blob/master/docker/fetchsse.js"
    click Docker "https://github.com/easychen/openai-api-proxy/tree/master/docker/"
    click CF "https://github.com/easychen/openai-api-proxy/blob/master/FUNC.md"
    click MainPkg "https://github.com/easychen/openai-api-proxy/blob/master/package.json"
    click DockerPkg "https://github.com/easychen/openai-api-proxy/blob/master/docker/package.json"
    click Readme "https://github.com/easychen/openai-api-proxy/blob/master/README.md"
    click ReadmeCN "https://github.com/easychen/openai-api-proxy/blob/master/README.CN.md"
    click License "https://github.com/easychen/openai-api-proxy/tree/master/LICENSE"
    click GitIgnore "https://github.com/easychen/openai-api-proxy/blob/master/.gitignore"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef external fill:#C8FACC,stroke:#22863a,color:#22863a;
    classDef deploy fill:#FFE4B3,stroke:#d18616,color:#d18616;
    classDef docs fill:#F2F2F2,stroke:#6a737d,color:#6a737d;
```
