# plexpt/chatgpt-java architecture

> Architecture diagram of the GitHub repository plexpt/chatgpt-java, 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/plexpt/chatgpt-java
- Repository: https://github.com/plexpt/chatgpt-java

## Overview

##### Project Type and Purpose
- This is an open-source Java SDK (library) for interacting with OpenAI’s ChatGPT REST and streaming APIs.
- It provides two primary client entry points: synchronous (ChatGPT) and streaming (ChatGPTStream).

##### File Structure
- Top-level:
- pom.xml (Maven coordinates, dependency management)
- src/main/java/com/plexpt/chatgpt – core packages
- .github/workflows – CI (publish to Maven Central)
- Key packages under com.plexpt.chatgpt:
- api – HTTP client wrapper (Api.java)
- entity – request/response models for chat, images, audio, billing
- exception – custom SDK exception (ChatException)
- listener – streaming handlers (ConsoleStreamListener, SseStreamListener)
- util – support classes (Proxy construction, JSON via fastjson, Token counting, SSE helper, Date formatting, Context holder)
- Tests live under src/test/java/com/plexpt/chatgpt to verify streaming and function-call workflows.

##### Extract Insights from the README
- Features: chat, streaming, function calls, embeddings, image generation, audio transcription, billing usage, token counting, multi-key rotation, proxy support, context management.
- Usage: builder pattern for ChatGPT/ChatGPTStream, injecting apiKey(s), proxy, timeout, apiHost.
- Two execution modes:
- chatCompletion (single HTTP POST)
- streamChatCompletion (SSE style streaming with listeners)
- Integration example: Spring’s SseEmitter via SseStreamListener.

##### Core Components & Interactions
a. Main Components
1. SDK Client Layer
– ChatGPT (synchronous client)
– ChatGPTStream (streaming client)
– ConsoleChatGPT (demo CLI)
2. API Layer
– Api.java: constructs and executes HTTP requests (POST to OpenAI endpoints)
3. Domain Models
– entity package: ChatCompletionRequest, ChatCompletionResponse, Message, AudioResponse, ImageResponse, UsageResponse, etc.
4. Utilities
– Proxy builder (Proxys.java)
– JSON mapping (JSON, JSONObject in fastjson wrapper)
– Token counter (TokensUtil)
– Context manager (ChatContextHolder)
– SSE helper (SseHelper)
5. Streaming Listeners
– AbstractStreamListener (base)
– ConsoleStreamListener (prints to console)
– SseStreamListener (bridges to Spring SseEmitter)
6. Exception Handling
– ChatException for wrapping HTTP or parsing errors
7. External Systems
– OpenAI REST API (api.openai.com or reverse proxy)

b. Relationships & Data Flow
- Client Layer (ChatGPT or ChatGPTStream) is configured via Builder (apiKey(s), proxy, host, timeout).
- On invocation (chatCompletion or streamChatCompletion), client delegates to Api.java.
- Api.java serializes domain model → HTTP request → sends to OpenAI endpoint.
- Response is deserialized into entity objects (BaseResponse subclasses).
- In streaming mode, Api.java opens an SSE connection and pushes chunks into a StreamListener.
- StreamListener callbacks propagate data back to application code (console, SSE emitter, or custom listener).
- Utilities provide cross-cutting support: JSON parsing, date formatting, token counting, context storage, and proxy handling.
- Errors bubble up as ChatException.

c. Architectural Patterns & Principles
- Builder Pattern for client configuration.
- Layered architecture: Client API → HTTP layer → Domain entities → Util/Listener.
- Observer pattern for streaming (listeners subscribe to events).
- Separation of concerns:
- Domain models separate from HTTP transport.
- Utilities isolated from core client logic.
- Extensibility: Users can implement their own StreamListener or extend entity classes if needed.

d. Key Technologies & Frameworks
- Java 8+
- Fastjson (via shaded util/fastjson packages)
- Java HTTP client (HttpURLConnection or HttpClient inside Api.java)
- Spring SseEmitter (illustrated via SseStreamListener)
- Maven (dependency management & publishing)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        ChatGPT["ChatGPT"]:::core
        ChatGPTStream["ChatGPTStream"]:::core
        ConsoleChatGPT["ConsoleChatGPT"]:::core
    end

    subgraph "API Layer"
        Api["Api"]:::core
    end

    subgraph "Domain Models"
        BaseResponse["BaseResponse"]:::core
        ChatModels["chat/*"]:::core
        AudioModels["audio/*"]:::core
        ImageModels["images/*"]:::core
        EmbeddingModels["embedding/*"]:::core
        BillingModels["billing/*"]:::core
    end

    subgraph "Utilities"
        Proxys["Proxys"]:::util
        JSON["JSON, JSONObject, etc."]:::util
        TokensUtil["TokensUtil"]:::util
        ChatContextHolder["ChatContextHolder"]:::util
        SseHelper["SseHelper"]:::util
        FormatDateUtil["FormatDateUtil"]:::util
    end

    subgraph "Listeners"
        AbstractStreamListener["AbstractStreamListener"]:::listener
        ConsoleStreamListener["ConsoleStreamListener"]:::listener
        SseStreamListener["SseStreamListener"]:::listener
    end

    subgraph "Exception"
        ChatException["ChatException"]:::exception
    end

    subgraph "External Services"
        OpenAI["OpenAI REST API"]:::external
    end

    ChatGPT -->|uses| Api
    ChatGPTStream -->|uses SSE| Api
    ConsoleChatGPT -->|invokes| ChatGPTStream

    Api -->|POST /chat/completions| OpenAI
    OpenAI -->|response| Api
    Api -->|deserialize| BaseResponse
    BaseResponse -->|models| ChatModels
    BaseResponse -->|models| AudioModels
    BaseResponse -->|models| ImageModels
    BaseResponse -->|models| EmbeddingModels
    BaseResponse -->|models| BillingModels

    ChatGPT -->|config| Proxys
    ChatGPT -->|parsing| JSON
    ChatGPT -->|token counting| TokensUtil
    ChatGPT -->|context| ChatContextHolder
    Api -->|proxy| Proxys
    Api -->|JSON parse| JSON
    Api -->|context access| ChatContextHolder

    Api -->|SSE chunks| AbstractStreamListener
    AbstractStreamListener -->|implements| ConsoleStreamListener
    AbstractStreamListener -->|implements| SseStreamListener
    ConsoleStreamListener -->|outputs to| ConsoleChatGPT
    SseStreamListener -->|emits via| OpenAI

    ChatGPT -->|errors| ChatException
    ChatGPTStream -->|errors| ChatException
    Api -->|errors| ChatException
    AbstractStreamListener -->|errors| ChatException

    classDef core fill:#cce5ff,stroke:#004085,color:#004085;
    classDef util fill:#d4edda,stroke:#155724,color:#155724;
    classDef listener fill:#fff3cd,stroke:#856404,color:#856404;
    classDef exception fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;

    click ChatGPT "https://github.com/plexpt/chatgpt-java/blob/main/src/main/java/com/plexpt/chatgpt/ChatGPT.java"
    click ChatGPTStream "https://github.com/plexpt/chatgpt-java/blob/main/src/main/java/com/plexpt/chatgpt/ChatGPTStream.java"
    click ConsoleChatGPT "https://github.com/plexpt/chatgpt-java/blob/main/src/main/java/com/plexpt/chatgpt/ConsoleChatGPT.java"
    click Api "https://github.com/plexpt/chatgpt-java/blob/main/src/main/java/com/plexpt/chatgpt/api/Api.java"
    click BaseResponse "https://github.com/plexpt/chatgpt-java/blob/main/src/main/java/com/plexpt/chatgpt/entity/BaseResponse.java"
    click ChatModels "https://github.com/plexpt/chatgpt-java/tree/main/src/main/java/com/plexpt/chatgpt/entity/chat/"
    click AudioModels "https://github.com/plexpt/chatgpt-java/tree/main/src/main/java/com/plexpt/chatgpt/entity/audio/"
    click ImageModels "https://github.com/plexpt/chatgpt-java/tree/main/src/main/java/com/plexpt/chatgpt/entity/images/"
    click EmbeddingModels "https://github.com/plexpt/chatgpt-java/tree/main/src/main/java/com/plexpt/chatgpt/entity/embedding/"
    click BillingModels "https://github.com/plexpt/chatgpt-java/tree/main/src/main/java/com/plexpt/chatgpt/entity/billing/"
    click ChatException "https://github.com/plexpt/chatgpt-java/blob/main/src/main/java/com/plexpt/chatgpt/exception/ChatException.java"
    click AbstractStreamListener "https://github.com/plexpt/chatgpt-java/blob/main/src/main/java/com/plexpt/chatgpt/listener/AbstractStreamListener.java"
    click ConsoleStreamListener "https://github.com/plexpt/chatgpt-java/blob/main/src/main/java/com/plexpt/chatgpt/listener/ConsoleStreamListener.java"
    click SseStreamListener "https://github.com/plexpt/chatgpt-java/blob/main/src/main/java/com/plexpt/chatgpt/listener/SseStreamListener.java"
    click Proxys "https://github.com/plexpt/chatgpt-java/blob/main/src/main/java/com/plexpt/chatgpt/util/Proxys.java"
    click JSON "https://github.com/plexpt/chatgpt-java/blob/main/src/main/java/com/plexpt/chatgpt/util/fastjson/JSON.java"
    click TokensUtil "https://github.com/plexpt/chatgpt-java/blob/main/src/main/java/com/plexpt/chatgpt/util/TokensUtil.java"
    click ChatContextHolder "https://github.com/plexpt/chatgpt-java/blob/main/src/main/java/com/plexpt/chatgpt/util/ChatContextHolder.java"
    click SseHelper "https://github.com/plexpt/chatgpt-java/blob/main/src/main/java/com/plexpt/chatgpt/util/SseHelper.java"
    click FormatDateUtil "https://github.com/plexpt/chatgpt-java/blob/main/src/main/java/com/plexpt/chatgpt/util/FormatDateUtil.java"
```
