# farishijazi/openai2civitai architecture

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

- Interactive diagram: https://gitdiagram.com/farishijazi/openai2civitai
- Repository: https://github.com/farishijazi/openai2civitai

## Overview

##### Project Type and Purpose
- This is a lightweight backend proxy server written in Python.
- It exposes an HTTP endpoint compatible with the OpenAI DALL-E image generation API (/v1/images/generations and /health).
- It’s meant to sit between an existing OpenAI-based client and the CivitAI service, requiring no client-side code changes other than pointing at this proxy.

##### High-Level Architecture & Components
a. External Clients
- Any OpenAI-compatible client (e.g., applications, cURL, Open-WebUI)
b. HTTP API Layer (`server.py`, `app.py`)
- `/v1/images/generations` – main proxy endpoint
- `/health` – health check
c. Configuration Layer (`config.py`, environment variables)
- Reads `CIVITAI_API_TOKEN`, `CIVITAI_DEFAULT_MODEL`, host/port, poll settings
d. Request Transformation
- `prompt_parser.py` – extracts and normalizes OpenAI-style JSON
- `prompt_reviser.py` – applies any additional parameter tweaks (e.g., size, flux mode)
e. CivitAI Client SDK (`openai2civitai/civitai_py/civitai_py`)
- Models (data classes) under `models/`
- Service clients under `services/` (e.g., `Jobs_service.py`, async variants)
- HTTP client and API config (`api_config.py`)
f. Job Polling & Response Aggregation
- Polls CivitAI until images are ready (`MAX_POLL_ATTEMPTS`, `POLL_INTERVAL`)
- Collects URLs or blobs, wraps them in OpenAI’s response schema
g. Tests & Examples
- `test_proxy.py` – end-to-end proxy test
- `openai2civitai/civitai_py/tests/` – unit tests for the SDK
- Example Streamlit demo under `examples/streamlit_demo`
h. Deployment
- Dockerfile, docker-compose.yml for containerized deployment
- GitHub Actions workflow for Docker publishing

##### Interactions & Data Flow
1. Client ➔ Proxy HTTP server
- Sends POST to `/v1/images/generations` with OpenAI JSON
2. Proxy
- Reads `config.py` for tokens and defaults
- `prompt_parser` and `prompt_reviser` convert request to CivitAI format
- Calls CivitAI SDK (`Jobs_service.create_image`, etc.)
3. CivitAI API
- Processes the job
- Proxy polls using the SDK’s async services until completion
4. Proxy
- Receives image URLs/blobs
- Wraps result in OpenAI image generation response format
5. Proxy ➔ Client
- Returns JSON mimicking the OpenAI response

##### Architectural Patterns & Design Principles
- Single-process HTTP “adapter” pattern (facade over CivitAI).
- Separation of concerns:
- API layer (FastAPI/Starlette or Flask alternative in `server.py`)
- Config layer (`config.py`)
- Transformation layer (`prompt_parser.py`, `prompt_reviser.py`)
- SDK layer (auto-generated CivitAI client under `civitai_py`)
- Polling mechanism as a resilience pattern for asynchronous CivitAI jobs.
- Containerization for easy deployment and portability.

##### Essential Elements
- Clear labels: e.g., “OpenAI Client,” “Proxy Server: /v1/images/generations,” “CivitAI SDK,” “CivitAI API.”
- Incoming HTTP request
- Outgoing SDK calls
- Polling loop
- Final HTTP response
- Blue for API boundaries
- Green for transformation/business logic
- Orange for third-party/external services

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        OpenAIClient["OpenAI-Compatible Client"]:::external
    end

    %% Docker Container Boundary
    subgraph "Docker Container"
        direction TB

        %% Proxy Server Layer
        subgraph "Proxy Server"
            direction TB
            ProxyAPI["Proxy HTTP API\n/v1/images/generations & /health"]:::api
            Config["Configuration\n(CIVITAI_API_TOKEN,\nCIVITAI_DEFAULT_MODEL,\nhost/port,poll)"]:::config
            PromptParser["Prompt Parser"]:::logic
            PromptReviser["Prompt Reviser"]:::logic
            PollingLogic["Job Polling & Response Aggregation"]:::logic
        end

        %% CivitAI SDK Layer
        subgraph "CivitAI SDK (vendored)"
            direction TB
            APIConfig["API Config"]:::sdk
            Models["Data Models"]:::sdk
            Services["Service Clients"]:::sdk
        end
    end

    %% External API Layer
    subgraph "External Services"
        direction TB
        CivitAIAPI["CivitAI API"]:::external
    end

    %% Deployment & Misc (dashed)
    subgraph "Deployment & Others" 
        direction TB
        DockerfileNode["Dockerfile"]:::dashed
        Compose["docker-compose.yml"]:::dashed
        Actions[".github/workflows/docker-publish.yml"]:::dashed
        Packaging["setup.py & requirements.txt"]:::dashed
        E2ETest["End-to-End Proxy Test"]:::dashed
        SDKTests["SDK Unit Tests"]:::dashed
        Demo["Streamlit Demo Example"]:::dashed
    end

    %% Connections
    OpenAIClient -->|POST /v1/images/generations| ProxyAPI
    ProxyAPI -->|load env vars| Config
    ProxyAPI -->|parse request| PromptParser
    PromptParser -->|revise request| PromptReviser
    PromptReviser -->|invoke SDK| Services
    Services -->|HTTP call| CivitAIAPI
    CivitAIAPI -->|job status| Services
    Services -->|deliver results to| PollingLogic
    PollingLogic -->|format response| ProxyAPI
    ProxyAPI -->|return JSON| OpenAIClient

    %% Dashed connections
    ProxyAPI -.->|tested by| E2ETest
    Services -.->|unit tests| SDKTests
    ProxyServerCallsDemo -.-> Demo

    %% Click Events
    click ProxyAPI "https://github.com/farishijazi/openai2civitai/blob/master/openai2civitai/server.py"
    click PollingLogic "https://github.com/farishijazi/openai2civitai/blob/master/openai2civitai/server.py"
    click PromptParser "https://github.com/farishijazi/openai2civitai/blob/master/openai2civitai/prompt_parser.py"
    click PromptReviser "https://github.com/farishijazi/openai2civitai/blob/master/openai2civitai/prompt_reviser.py"
    click APIConfig "https://github.com/farishijazi/openai2civitai/blob/master/openai2civitai/civitai_py/civitai/api_config.py"
    click Models "https://github.com/farishijazi/openai2civitai/tree/master/openai2civitai/civitai_py/civitai/models/"
    click Services "https://github.com/farishijazi/openai2civitai/tree/master/openai2civitai/civitai_py/civitai/services/"
    click E2ETest "https://github.com/farishijazi/openai2civitai/blob/master/test_proxy.py"
    click SDKTests "https://github.com/farishijazi/openai2civitai/tree/master/openai2civitai/civitai_py/tests/"
    click Demo "https://github.com/farishijazi/openai2civitai/tree/master/openai2civitai/civitai_py/examples/streamlit_demo/"
    click DockerfileNode "https://github.com/farishijazi/openai2civitai/tree/master/Dockerfile"
    click Compose "https://github.com/farishijazi/openai2civitai/blob/master/docker-compose.yml"
    click Actions "https://github.com/farishijazi/openai2civitai/blob/master/.github/workflows/docker-publish.yml"
    click Packaging "https://github.com/farishijazi/openai2civitai/blob/master/setup.py"
    
    %% Styles
    classDef api fill:#D0E8FF,stroke:#2A72B5,color:#2A72B5;
    classDef logic fill:#E8F8D0,stroke:#6B8E23,color:#6B8E23;
    classDef sdk fill:#FFF4D0,stroke:#DAA520,color:#DAA520;
    classDef external fill:#FDE8D0,stroke:#D9632B,color:#D9632B;
    classDef config fill:#E0E0E0,stroke:#888888,color:#333333;
    classDef dashed stroke-dasharray: 5 5,fill:#FFFFFF,color:#666666;
    class ProxyServerCallsDemo,DockerfileNode,Compose,Actions,Packaging,E2ETest,SDKTests,Demo dashed
```
