# d7ead/liboai architecture

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

- Interactive diagram: https://gitdiagram.com/d7ead/liboai
- Repository: https://github.com/d7ead/liboai

## Overview

##### Project Type and Purpose
- This is a C++17 client‐library (“liboai”) that wraps the OpenAI REST API in a set of idiomatic C++ classes and methods.
- It is not a standalone application but a reusable SDK, structured as a “spiritual port” of OpenAI’s Python library.

##### File Structure Analysis
- Top-level:
- CMakeLists.txt, shell.nix, flake.nix: build and environment configuration.
- .github/: CI and issue/PR templates.
- documentation/: per‐feature examples (audio, chat, completions, etc.).
- liboai/: the library itself, split into:
- core/: authorization, networking abstraction, response handling.
- components/: one .cpp per API surface (audio, chat, images, files, etc.).
- /: public headers mirroring core/ and components/.
- External dependencies declared in README: cURL (HTTP transport) and nlohmann-json (serialization).

##### README Insights
- Confirms modular components (Chat, Audio, Azure, Completions, etc.).
- Describes usage pattern: user creates an OpenAI facade object, sets credentials, invokes component methods synchronously or asynchronously.
- Highlights C++17, vcpkg recommendation, and similarity to Python API.

a. Main Components
- User Application: the client code that `#include "liboai.h"`.
- OpenAI Facade (liboai::OpenAI): entry point exposing pointers/references to each component.
- Components Layer: Audio, Chat, Completions, Edits, Embeddings, Files, Fine-Tunes, Images, Models, Moderations, Azure.
- Core Layer:
– Authorization (manages API keys, proxies)
– NetImpl (HTTP client abstraction)
– Network (builds requests, dispatches via cURL)
– Response (parses JSON into a generic Response object)
- External Dependencies: cURL for HTTP; nlohmann-json for JSON serialization/deserialization.
- External Services: OpenAI’s REST endpoints (api.openai.com) and Azure OpenAI endpoints.

b. Relationships and Data Flow
1. User Application → OpenAI Facade: calls `oai.Chat->create(...)`
2. OpenAI Facade → Components: delegates call to the appropriate component class.
3. Component → Core Network Layer: builds JSON payload, calls NetImpl.
4. Core → cURL: sends HTTPS request to OpenAI/Azure.
5. Service → cURL: returns HTTP response.
6. Core Response Layer → parses JSON via nlohmann-json, wraps in `Response` object.
7. Response → Component → back to User Application.

c. Architectural Patterns and Principles
- Facade: `liboai::OpenAI` centralizes access.
- Layered Architecture: clear separation between API surface (components) and transport/serialization (core).
- Abstraction & Strategy: NetImpl isolates HTTP client (you could swap cURL for another).
- Modularity: each OpenAI feature lives in its own component.

d. Technologies and Frameworks
- C++17, CMake, shell.nix/flake.nix.
- vcpkg (recommended) or system installs for cURL and nlohmann-json.
- cURL: HTTP transport.
- nlohmann-json: JSON handling.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "Application Layer"
        direction TB
        UserApp["User Application"]:::app
    end

    subgraph "Facade Layer"
        direction TB
        Facade["liboai::OpenAI"]:::facade
    end

    subgraph "Components Layer"
        direction TB
        Audio["Audio Component"]:::component
        Chat["Chat Component"]:::component
        Completions["Completions Component"]:::component
        Edits["Edits Component"]:::component
        Embeddings["Embeddings Component"]:::component
        Files["Files Component"]:::component
        FineTunes["Fine-Tunes Component"]:::component
        Images["Images Component"]:::component
        Models["Models Component"]:::component
        Moderations["Moderations Component"]:::component
        AzureComp["Azure Component"]:::component
    end

    subgraph "Core Layer"
        direction TB
        Auth["Authorization"]:::core
        Network["Network Request Builder"]:::core
        NetImpl["NetImpl (HTTP Abstraction)"]:::core
        Response["Response Handling"]:::core
    end

    subgraph "External Dependencies"
        direction TB
        CURL["cURL"]:::dep
        JSON["nlohmann-json"]:::dep
    end

    subgraph "External Services"
        direction TB
        OpenAIService["OpenAI REST API"]:::service
        AzureService["Azure OpenAI API"]:::service
    end

    %% Connections
    UserApp -->|"includes & calls"| Facade
    Facade -->|"delegates calls to"| Audio
    Facade -->|"delegates calls to"| Chat
    Facade -->|"delegates calls to"| Completions
    Facade -->|"delegates calls to"| Edits
    Facade -->|"delegates calls to"| Embeddings
    Facade -->|"delegates calls to"| Files
    Facade -->|"delegates calls to"| FineTunes
    Facade -->|"delegates calls to"| Images
    Facade -->|"delegates calls to"| Models
    Facade -->|"delegates calls to"| Moderations
    Facade -->|"delegates calls to"| AzureComp

    %% Component to Core
    Audio -->|"builds payload"| Network
    Chat -->|"builds payload"| Network
    Completions -->|"builds payload"| Network
    Edits -->|"builds payload"| Network
    Embeddings -->|"builds payload"| Network
    Files -->|"builds payload"| Network
    FineTunes -->|"builds payload"| Network
    Images -->|"builds payload"| Network
    Models -->|"builds payload"| Network
    Moderations -->|"builds payload"| Network
    AzureComp -->|"builds payload"| Network

    Network -->|"requests API key"| Auth
    Network -->|"forwards request to"| NetImpl
    NetImpl -->|"sends HTTP"| CURL
    NetImpl -->|"receives HTTP response"| Response
    Response -->|"parses JSON"| JSON
    Response -->|"returns Response object to"| Chat
    Response -->|"returns Response object to"| Audio
    Response -->|"returns Response object to"| Completions
    Response -->|"returns Response object to"| Edits
    Response -->|"returns Response object to"| Embeddings
    Response -->|"returns Response object to"| Files
    Response -->|"returns Response object to"| FineTunes
    Response -->|"returns Response object to"| Images
    Response -->|"returns Response object to"| Models
    Response -->|"returns Response object to"| Moderations
    Response -->|"returns Response object to"| AzureComp

    %% Core to Services
    CURL -->|"HTTPS to"| OpenAIService
    CURL -->|"HTTPS to"| AzureService

    %% Return path
    Chat -->|"response propagation"| UserApp
    Audio -->|"response propagation"| UserApp
    Completions -->|"response propagation"| UserApp
    Edits -->|"response propagation"| UserApp
    Embeddings -->|"response propagation"| UserApp
    Files -->|"response propagation"| UserApp
    FineTunes -->|"response propagation"| UserApp
    Images -->|"response propagation"| UserApp
    Models -->|"response propagation"| UserApp
    Moderations -->|"response propagation"| UserApp
    AzureComp -->|"response propagation"| UserApp

    %% Click Events
    click Facade "https://github.com/d7ead/liboai/blob/main/liboai/include/liboai.h"
    click Auth "https://github.com/d7ead/liboai/blob/main/liboai/include/core/authorization.h"
    click Auth "https://github.com/d7ead/liboai/blob/main/liboai/core/authorization.cpp"
    click NetImpl "https://github.com/d7ead/liboai/blob/main/liboai/include/core/netimpl.h"
    click NetImpl "https://github.com/d7ead/liboai/blob/main/liboai/core/netimpl.cpp"
    click Network "https://github.com/d7ead/liboai/blob/main/liboai/include/core/network.h"
    click Response "https://github.com/d7ead/liboai/blob/main/liboai/include/core/response.h"
    click Response "https://github.com/d7ead/liboai/blob/main/liboai/core/response.cpp"
    click Audio "https://github.com/d7ead/liboai/blob/main/liboai/include/components/audio.h"
    click Audio "https://github.com/d7ead/liboai/blob/main/liboai/components/audio.cpp"
    click Chat "https://github.com/d7ead/liboai/blob/main/liboai/include/components/chat.h"
    click Chat "https://github.com/d7ead/liboai/blob/main/liboai/components/chat.cpp"
    click Completions "https://github.com/d7ead/liboai/blob/main/liboai/include/components/completions.h"
    click Completions "https://github.com/d7ead/liboai/blob/main/liboai/components/completions.cpp"
    click Edits "https://github.com/d7ead/liboai/blob/main/liboai/include/components/edits.h"
    click Edits "https://github.com/d7ead/liboai/blob/main/liboai/components/edits.cpp"
    click Embeddings "https://github.com/d7ead/liboai/blob/main/liboai/include/components/embeddings.h"
    click Embeddings "https://github.com/d7ead/liboai/blob/main/liboai/components/embeddings.cpp"
    click Files "https://github.com/d7ead/liboai/blob/main/liboai/include/components/files.h"
    click Files "https://github.com/d7ead/liboai/blob/main/liboai/components/files.cpp"
    click FineTunes "https://github.com/d7ead/liboai/blob/main/liboai/include/components/fine_tunes.h"
    click FineTunes "https://github.com/d7ead/liboai/blob/main/liboai/components/fine_tunes.cpp"
    click Images "https://github.com/d7ead/liboai/blob/main/liboai/include/components/images.h"
    click Images "https://github.com/d7ead/liboai/blob/main/liboai/components/images.cpp"
    click Models "https://github.com/d7ead/liboai/blob/main/liboai/include/components/models.h"
    click Models "https://github.com/d7ead/liboai/blob/main/liboai/components/models.cpp"
    click Moderations "https://github.com/d7ead/liboai/blob/main/liboai/include/components/moderations.h"
    click Moderations "https://github.com/d7ead/liboai/blob/main/liboai/components/moderations.cpp"
    click AzureComp "https://github.com/d7ead/liboai/blob/main/liboai/include/components/azure.h"
    click AzureComp "https://github.com/d7ead/liboai/blob/main/liboai/components/azure.cpp"

    %% Styles
    classDef app fill:#a8f0c6,stroke:#333,stroke-width:1px;
    classDef facade fill:#b3d4fc,stroke:#333,stroke-width:1px;
    classDef component fill:#b3d4fc,stroke:#333,stroke-width:1px;
    classDef core fill:#c0d6e4,stroke:#333,stroke-width:1px;
    classDef dep fill:#ffd8a8,stroke:#333,stroke-width:1px;
    classDef service fill:#e1c9f7,stroke:#333,stroke-width:1px;
```
