# chihebnabil/openai-api-mock architecture

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

- Interactive diagram: https://gitdiagram.com/chihebnabil/openai-api-mock
- Repository: https://github.com/chihebnabil/openai-api-mock

## Overview

##### Project type and purpose
- This is an open-source Node.js library (module) whose sole purpose is to mock OpenAI API endpoints in a development or test environment. It doesn’t stand up servers or offer a UI—it hooks into HTTP calls made by an OpenAI client and returns synthetic responses for chat completions (normal and streaming) and image generation.

##### File structure
- Top-level files:
- package.json, package-lock.json, vite.config.js – build and dependency metadata
- jest.config.js, __tests__/… – test suite
- .github/workflows/test.yml – CI integration
- src/ directory:
- index.js – main export (`mockOpenAIResponse`)
- chat.js – mocks non-stream chat completions
- chat.stream.js – mocks streaming chat completions
- image.js – mocks image generation endpoints
- utils/
– fakeDataGenerators.js – builds fake chat/image content (leverages @faker-js/faker)
- Third-party intercept library: nock

##### README for additional insights
- The README confirms usage patterns (`mockOpenAIResponse(force, options)`), supported endpoints, and custom endpoint registration via `mock.addCustomEndpoint()`.
- It documents simulated latency, error injection, and request logging features.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    ClientApp["Client Application"]:::external
    ExternalAPI["OpenAI API (Real)"]:::external

    %% Library: openai-api-mock
    subgraph "openai-api-mock" 
        mockIndex["mockOpenAIResponse()\\n(initializer & addCustomEndpoint)"]:::internals
        NockInterceptor["Nock Interceptor"]:::internals
        subgraph "Mock Handlers"
            ChatMock["ChatMock\\nPOST /v1/chat/completions"]:::internals
            ChatStreamMock["ChatStreamMock\\nPOST /v1/chat/completions (stream)"]:::internals
            ImageMock["ImageMock\\nPOST /v1/images/generations"]:::internals
        end
        subgraph "Utils"
            ResponseGenerators["ResponseGenerators"]:::utils
            FakeDataGenerators["FakeDataGenerators"]:::utils
        end
    end

    %% Repository Configurations
    subgraph "Repository Config"
        TestSuite["Jest Test Suite\\n__tests__/"]:::config
        CIConfig["CI Workflow\\n.github/workflows/test.yml"]:::config
        BuildMeta["Build Metadata\\npackage.json, package-lock.json, vite.config.js"]:::config
    end

    %% Flows
    ClientApp -->|"initialize mock"| mockIndex
    mockIndex -->|"configures"| NockInterceptor
    ClientApp -->|"HTTP Request"| NockInterceptor

    NockInterceptor -->|"POST /v1/chat/completions"| ChatMock
    NockInterceptor -->|"POST /v1/chat/completions (stream)"| ChatStreamMock
    NockInterceptor -->|"POST /v1/images/generations"| ImageMock
    NockInterceptor -.->|"passthrough if no match / mock disabled"| ExternalAPI

    ChatMock -->|calls| ResponseGenerators
    ChatStreamMock -->|calls| ResponseGenerators
    ImageMock -->|calls| ResponseGenerators

    ResponseGenerators -->|uses| FakeDataGenerators

    ChatMock -->|"HTTP Response"| ClientApp
    ChatStreamMock -->|"HTTP Response (stream)"| ClientApp
    ImageMock -->|"HTTP Response"| ClientApp

    %% Click Events
    click mockIndex "https://github.com/chihebnabil/openai-api-mock/blob/dev/src/index.js"
    click ChatMock "https://github.com/chihebnabil/openai-api-mock/blob/dev/src/chat.js"
    click ChatStreamMock "https://github.com/chihebnabil/openai-api-mock/blob/dev/src/chat.stream.js"
    click ImageMock "https://github.com/chihebnabil/openai-api-mock/blob/dev/src/image.js"
    click FakeDataGenerators "https://github.com/chihebnabil/openai-api-mock/blob/dev/src/utils/fakeDataGenerators.js"
    click ResponseGenerators "https://github.com/chihebnabil/openai-api-mock/blob/dev/src/utils/responseGenerators.js"
    click TestSuite "https://github.com/chihebnabil/openai-api-mock/tree/dev/__tests__/"
    click CIConfig "https://github.com/chihebnabil/openai-api-mock/blob/dev/.github/workflows/test.yml"
    click BuildMeta "https://github.com/chihebnabil/openai-api-mock/blob/dev/package.json"

    %% Styles
    classDef external fill:#eeeeee,stroke:#999,stroke-width:1px
    classDef internals fill:#bbdefb,stroke:#1e88e5,stroke-width:1px
    classDef utils fill:#c8e6c9,stroke:#43a047,stroke-width:1px
    classDef config fill:#ffe082,stroke:#ffa000,stroke-width:1px
```
