# mingzilla/llm-client architecture

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

- Interactive diagram: https://gitdiagram.com/mingzilla/llm-client
- Repository: https://github.com/mingzilla/llm-client

## Overview

##### Project type and purpose
- This is a standalone Java client library module (llm-client) built with Spring WebFlux.
- Purpose: Provide a non-blocking, reactive interface to generic LLM (Large Language Model) HTTP APIs, with support for regular, JSON-streaming and SSE-streaming calls, error handling, and pre-flight validation.

##### File structure
- Top-level build files: build.gradle, settings.gradle, gradle wrapper, GitHub workflows.
- src/main/java/io/github/mingzilla/llmclient: core client class (LlmClient), domain models (LlmClientInput, LlmClientOutput, LlmClientError, etc.), JSON utilities, verifier and preflight exception.
- src/test/java/...: unit tests for every domain/model class and client methods.
- No “frontend” or “backend” directories because this is a library module.
- Configuration class (LlmClientConfig) provides WebClient bean and instantiates LlmClient.

##### README for technical stack and design principles
- Built on Spring WebFlux with Reactor Netty HttpClient.
- Fully reactive, non-blocking I/O.
- Separation of concerns: input builders, output models, JSON serialization, streaming.
- Uses Java records for immutable domain types.
- Error handling via LlmClientError and LlmClientPreflightException.

##### Main components
a. Consumer Application
- Any Spring/WebFlux service or controller that calls LlmClient.verifyAndSend / verifyAndStream / verifyAndStreamSse.
b. LlmClient Module
- Public API (methods: verifyAndSend, verifyAndStream, verifyAndStreamSse)
- Preflight Verifier (LlmClientVerifier)
- Input Builder (LlmClientInput / LlmClientInputBody / LlmClientMessage)
- JSON Utilities (LlmClientJsonUtil)
- Output Models (LlmClientOutput / LlmClientOutputChunk)
- Exception Handling (LlmClientPreflightException, LlmClientError)
c. Spring WebClient Layer
- WebClient bean configured via ReactorClientHttpConnector and Netty HttpClient
d. Network / HTTP Connector
- Reactor Netty HttpClient (connect timeout, response timeout)
e. External LLM API Provider
- Endpoints: /chat/json, /chat/stream, /chat/sse
- Returns JSON, chunked NDJSON, or SSE events
f. Supporting Libraries
- Spring WebFlux, Reactor Core, Netty, Jackson or other JSON parser

##### Relationships and data flows
- The Consumer Application invokes LlmClient.verifyAnd… methods.
- LlmClient internally calls the Preflight Verifier lambda; may throw LlmClientPreflightException on validation or rate limiting.
- If preflight passes, LlmClient uses Input Builder to construct an HTTP request payload.
- WebClient sends the request over Reactor Netty HttpClient to the External LLM API.
- Response is handled reactively:
- for non-streaming: WebClient retrieves full JSON → JSON Utilities parses into LlmClientOutput → returns Mono<LlmClientOutput>
- for JSON streaming: WebClient returns a Flux of LlmClientOutputChunk parsed by JSON Utilities
- for SSE streaming: WebClient returns Flux<ServerSentEvent<?>>
- The Consumer Application subscribes to the returned Mono/Flux.

##### Architectural patterns and design principles
- Reactive non-blocking pipeline (Publisher → Subscriber)
- Separation of concerns: input construction, HTTP transport, JSON parsing, error handling
- Immutability: use of Java records for domain types
- Preflight validation strategy via exceptions for early exit
- Bean configuration for testability and DI (LlmClientConfig)

##### Elements
- Consumer → LlmClient.verify…
- LlmClient → Preflight Verifier → (exception) or (continue)
- LlmClient → WebClient.request → Reactor Netty → External API
- External API → Reactor Netty → WebClient → JSON parser → LlmClientOutputChunk/Output → Consumer
- Annotations for protocols and formats: HTTP, JSON, SSE, NDJSON

## Diagram (Mermaid)

```mermaid
flowchart TD
    ConsumerApp["Consumer Application"]:::external

    subgraph "LlmClient Module"
        PublicAPI["LlmClient.verifyAnd...()"]:::library
        Preflight["LlmClientVerifier"]:::library
        ExceptionPF["LlmClientPreflightException"]:::library
        ExceptionError["LlmClientError"]:::library
        subgraph "Input Builders"
            Input["LlmClientInput"]:::library
            InputBody["LlmClientInputBody"]:::library
            Msg["LlmClientMessage"]:::library
        end
        JsonUtil["LlmClientJsonUtil"]:::library
        subgraph "Models"
            Output["LlmClientOutput"]:::library
            Chunk["LlmClientOutputChunk"]:::library
        end
    end

    WebClient["WebClient"]:::library
    ReactorNetty["Reactor Netty HttpClient"]:::library
    ExternalAPI["External LLM API\n(chat/json, /chat/stream, /chat/sse)"]:::external

    ConsumerApp -->|"invoke"| PublicAPI
    PublicAPI -->|"preflight validate"| Preflight
    Preflight -- "throws" --> ExceptionPF
    Preflight -- "valid" --> PublicAPI
    PublicAPI -->|"build input"| Input
    Input --> InputBody
    InputBody --> Msg
    PublicAPI -->|"serialize JSON"| JsonUtil
    PublicAPI -->|"invoke HTTP"| WebClient
    WebClient -->|"uses"| ReactorNetty
    ReactorNetty -->|"HTTP request"| ExternalAPI
    ExternalAPI -->|"HTTP response"| ReactorNetty
    ReactorNetty --> WebClient

    subgraph "Response Handling"
        WebClient -->|"non-stream JSON"| JsonUtil
        JsonUtil --> Output
        WebClient -->|"stream NDJSON"| JsonUtil
        JsonUtil --> Chunk
        WebClient -->|"SSE events"| Chunk
    end

    Output -->|"return Mono"| ConsumerApp
    Chunk -->|"return Flux"| ConsumerApp

    click PublicAPI "https://github.com/mingzilla/llm-client/blob/main/src/main/java/io/github/mingzilla/llmclient/LlmClient.java"
    click Preflight "https://github.com/mingzilla/llm-client/blob/main/src/main/java/io/github/mingzilla/llmclient/LlmClientVerifier.java"
    click Input "https://github.com/mingzilla/llm-client/blob/main/src/main/java/io/github/mingzilla/llmclient/LlmClientInput.java"
    click InputBody "https://github.com/mingzilla/llm-client/blob/main/src/main/java/io/github/mingzilla/llmclient/LlmClientInputBody.java"
    click Msg "https://github.com/mingzilla/llm-client/blob/main/src/main/java/io/github/mingzilla/llmclient/LlmClientMessage.java"
    click JsonUtil "https://github.com/mingzilla/llm-client/blob/main/src/main/java/io/github/mingzilla/llmclient/LlmClientJsonUtil.java"
    click Output "https://github.com/mingzilla/llm-client/blob/main/src/main/java/io/github/mingzilla/llmclient/LlmClientOutput.java"
    click Chunk "https://github.com/mingzilla/llm-client/blob/main/src/main/java/io/github/mingzilla/llmclient/LlmClientOutputChunk.java"
    click ExceptionPF "https://github.com/mingzilla/llm-client/blob/main/src/main/java/io/github/mingzilla/llmclient/LlmClientPreflightException.java"
    click ExceptionError "https://github.com/mingzilla/llm-client/blob/main/src/main/java/io/github/mingzilla/llmclient/LlmClientError.java"

    classDef library fill:#e0f7fa,stroke:#006064,color:#000
    classDef external fill:#eceff1,stroke:#90a4ae,color:#000
```
