# masaic-ai-platform/open-responses architecture

> Architecture diagram of the GitHub repository masaic-ai-platform/open-responses, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/masaic-ai-platform/open-responses
- Repository: https://github.com/masaic-ai-platform/open-responses

## Overview

##### Project Type and Purpose
- The project is a full-stack API service built in Kotlin (using Gradle as a build system) that implements the OpenAI Responses API specification.
- Its purpose is to provide a standardized interface to multiple LLM providers, enabling developers to switch between models (including OpenAI, Groq, Claude, etc.) easily. It also supports built-in tools (such as web search and GitHub search) via a consistent API.

##### Main Components
a. API Gateway / Endpoint Layer:
– Represent the public API endpoint (e.g., routes like POST /v1/responses, GET /v1/responses/{responseId}) that receive incoming requests.
– This layer is implemented by the Controllers (such as PlaygroundController and ResponseController) under the controller package.

b. Controller Layer:
– This part should capture how incoming HTTP requests are routed into the system.
– Controllers are responsible for request validation, error handling (ExceptionHandler), and delegating work to the service layer.

c. Service Layer:
– Illustrate components like MasaicResponseService and related services that process requests and apply business logic.
– This layer bridges the controller with client integration and external calls to the LLM providers.

d. Client / Integration Layer:
– Include the API client implementations (e.g., MasaicOpenAiResponseServiceImpl, ChatCompletionConverter, ChatCompletionChunkConverter, etc.) that handle communication with external LLM providers.
– This layer manages conversions (MasaicParameterConverter) and streaming requests (MasaicStreamingService).

e. Configuration and Utility Systems:
– Show the configuration components (LoggingConfig, MetricsConfig, WebFluxConfig, ThreadPoolConfig) which set up the reactive web framework (likely Spring WebFlux) and manage logging, threading, metrics, etc.
– Include external configuration files (e.g., application.properties, logback-spring.xml) which configure the runtime behavior of the system.

f. Tools and MCP Integration:
– Represent the dedicated modules for tool support (in the “tool” and “tool/mcp” directories).

g. Data Models and Converters:
– Include components under the model packages that define shared data structures (Models.kt, ToolModels.kt, etc.) which are used to standardize API user input and outgoing responses.
– Data conversion utilities also appear here.

h. Test Infrastructure:

##### Relationships & Interactions
- An API Gateway or load balancer (if applicable) routes the request to a Controller in the API layer.
- The Controller validates and forwards the request to a Service component which contains business logic.
- The Service then interacts with Client/Integration components to make calls to external LLM providers and, if needed, the Tools modules for any tool-specific logic.
- Once processing is complete, response data is formatted (with converters/formatters) and sent back through the Controller to the client.

##### Architectural Patterns
- The design is modular, following principles of separation of concerns often seen in MVC-like architectures.
- Use of dependency inversion: Controllers call Services, and Services depend on client adapters to interface with external systems.
- Use of configuration management with a dedicated config package and externalized configuration files.
- Recognize that Spring Boot (or Spring WebFlux) is likely used for dependency injection, lifecycle management, and reactive processing.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Client
    subgraph "External Client"
        Client("Client"):::client
    end

    %% API Gateway / Endpoint Layer
    subgraph "API Gateway / Endpoint Layer"
        PlaygroundController("PlaygroundController"):::endpoint
        ResponseController("ResponseController"):::endpoint
    end

    %% Controller Layer
    subgraph "Controller Layer"
        ControllerPackage("Controller Package"):::controller
        ExceptionHandler("ExceptionHandler"):::controller
    end

    %% Service Layer
    subgraph "Service Layer"
        MasaicResponseService("MasaicResponseService"):::service
    end

    %% Client / Integration Layer
    subgraph "Client / Integration Layer"
        MasaicOpenAiResponseServiceImpl("MasaicOpenAiResponseServiceImpl"):::integration
        ChatCompletionConverter("ChatCompletionConverter"):::integration
        ChatCompletionChunkConverter("ChatCompletionChunkConverter"):::integration
        MasaicParameterConverter("MasaicParameterConverter"):::integration
        MasaicStreamingService("MasaicStreamingService"):::integration
        MasaicToolHandler("MasaicToolHandler"):::integration
    end

    %% Configuration & Utility Systems
    subgraph "Configuration & Utility Systems"
        LoggingConfig("LoggingConfig"):::config
        MetricsConfig("MetricsConfig"):::config
        ThreadPoolConfig("ThreadPoolConfig"):::config
        WebFluxConfig("WebFluxConfig"):::config
        SensitiveDataMaskingConverter("SensitiveDataMaskingConverter"):::config
        ApplicationProperties("application.properties"):::config
        LogbackSpring("logback-spring.xml"):::config
    end

    %% Tools & MCP Integration
    subgraph "Tools & MCP Integration"
        ToolService("ToolService"):::tools
        ToolModels("ToolModels"):::tools
        MCPToolRegistry("MCPToolRegistry"):::tools
        MCPToolModels("MCPToolModels"):::tools
    end

    %% Data Models and Converters
    subgraph "Data Models and Converters"
        Models("Models"):::models
    end

    %% Test Infrastructure
    subgraph "Test Infrastructure"
        Tests("Tests"):::test
    end

    %% -------- Flow Connections --------
    Client -->|"HTTPrequest"| PlaygroundController
    Client -->|"HTTPrequest"| ResponseController

    %% Controllers delegate to Service
    PlaygroundController -->|"delegates"| MasaicResponseService
    ResponseController -->|"delegates"| MasaicResponseService

    %% Service calls integration components
    MasaicResponseService -->|"calls"| MasaicOpenAiResponseServiceImpl
    MasaicResponseService -->|"calls"| ChatCompletionConverter
    MasaicResponseService -->|"calls"| ChatCompletionChunkConverter
    MasaicResponseService -->|"calls"| MasaicParameterConverter
    MasaicResponseService -->|"calls"| MasaicStreamingService
    MasaicResponseService -->|"calls"| MasaicToolHandler

    %% Service formats responses using Models
    MasaicResponseService -->|"formats"| Models

    %% Service delegates to Tools integration
    MasaicResponseService -->|"invokes"| ToolService
    ToolService -->|"manages"| MCPToolRegistry
    ToolService -->|"uses"| ToolModels
    MCPToolRegistry -->|"associates"| MCPToolModels

    %% Error handling path (dotted)
    MasaicResponseService -.->|"error"| ExceptionHandler

    %% Configuration influencing components
    WebFluxConfig -->|"configures"| PlaygroundController
    ThreadPoolConfig -->|"configures"| MasaicResponseService
    MetricsConfig -->|"monitors"| MasaicResponseService
    LoggingConfig -->|"logs"| PlaygroundController
    SensitiveDataMaskingConverter -->|"masks"| MasaicResponseService
    ApplicationProperties -->|"externalConfig"| MasaicResponseService
    LogbackSpring -->|"loggingSetup"| PlaygroundController

    %% Test Infrastructure validates Service layer
    Tests -->|"tests"| MasaicResponseService

    %% -------- Styles --------
    classDef client fill:#D1C4E9,stroke:#311B92,stroke-width:2px;
    classDef endpoint fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef controller fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;
    classDef service fill:#FFF9C4,stroke:#F57F17,stroke-width:2px;
    classDef integration fill:#C5E1A5,stroke:#33691E,stroke-width:2px;
    classDef config fill:#FFCCBC,stroke:#BF360C,stroke-width:2px;
    classDef tools fill:#F8BBD0,stroke:#880E4F,stroke-width:2px;
    classDef models fill:#B2EBF2,stroke:#006064,stroke-width:2px;
    classDef test fill:#E0E0E0,stroke:#424242,stroke-width:2px;

    %% -------- Click Events --------
    click PlaygroundController "https://github.com/masaic-ai-platform/open-responses/blob/main/src/main/kotlin/ai/masaic/openresponses/api/controller/PlaygroundController.kt"
    click ResponseController "https://github.com/masaic-ai-platform/open-responses/blob/main/src/main/kotlin/ai/masaic/openresponses/api/controller/ResponseController.kt"
    click ExceptionHandler "https://github.com/masaic-ai-platform/open-responses/blob/main/src/main/kotlin/ai/masaic/openresponses/api/controller/ExceptionHandler.kt"
    click ControllerPackage "https://github.com/masaic-ai-platform/open-responses/tree/main/src/main/kotlin/ai/masaic/openresponses/api/controller"
    click MasaicResponseService "https://github.com/masaic-ai-platform/open-responses/blob/main/src/main/kotlin/ai/masaic/openresponses/api/service/MasaicResponseService.kt"
    click MasaicOpenAiResponseServiceImpl "https://github.com/masaic-ai-platform/open-responses/blob/main/src/main/kotlin/ai/masaic/openresponses/api/client/MasaicOpenAiResponseServiceImpl.kt"
    click ChatCompletionConverter "https://github.com/masaic-ai-platform/open-responses/blob/main/src/main/kotlin/ai/masaic/openresponses/api/client/ChatCompletionConverter.kt"
    click ChatCompletionChunkConverter "https://github.com/masaic-ai-platform/open-responses/blob/main/src/main/kotlin/ai/masaic/openresponses/api/client/ChatCompletionChunkConverter.kt"
    click MasaicParameterConverter "https://github.com/masaic-ai-platform/open-responses/blob/main/src/main/kotlin/ai/masaic/openresponses/api/client/MasaicParameterConverter.kt"
    click MasaicStreamingService "https://github.com/masaic-ai-platform/open-responses/blob/main/src/main/kotlin/ai/masaic/openresponses/api/client/MasaicStreamingService.kt"
    click MasaicToolHandler "https://github.com/masaic-ai-platform/open-responses/blob/main/src/main/kotlin/ai/masaic/openresponses/api/client/MasaicToolHandler.kt"
    click LoggingConfig "https://github.com/masaic-ai-platform/open-responses/blob/main/src/main/kotlin/ai/masaic/openresponses/api/config/LoggingConfig.kt"
    click MetricsConfig "https://github.com/masaic-ai-platform/open-responses/blob/main/src/main/kotlin/ai/masaic/openresponses/api/config/MetricsConfig.kt"
    click ThreadPoolConfig "https://github.com/masaic-ai-platform/open-responses/blob/main/src/main/kotlin/ai/masaic/openresponses/api/config/ThreadPoolConfig.kt"
    click WebFluxConfig "https://github.com/masaic-ai-platform/open-responses/blob/main/src/main/kotlin/ai/masaic/openresponses/api/config/WebFluxConfig.kt"
    click SensitiveDataMaskingConverter "https://github.com/masaic-ai-platform/open-responses/blob/main/src/main/kotlin/ai/masaic/openresponses/api/config/SensitiveDataMaskingConverter.kt"
    click ApplicationProperties "https://github.com/masaic-ai-platform/open-responses/blob/main/src/main/resources/application.properties"
    click LogbackSpring "https://github.com/masaic-ai-platform/open-responses/blob/main/src/main/resources/logback-spring.xml"
    click ToolService "https://github.com/masaic-ai-platform/open-responses/blob/main/src/main/kotlin/ai/masaic/openresponses/tool/ToolService.kt"
    click ToolModels "https://github.com/masaic-ai-platform/open-responses/blob/main/src/main/kotlin/ai/masaic/openresponses/tool/ToolModels.kt"
    click MCPToolRegistry "https://github.com/masaic-ai-platform/open-responses/blob/main/src/main/kotlin/ai/masaic/openresponses/tool/mcp/MCPToolRegistry.kt"
    click MCPToolModels "https://github.com/masaic-ai-platform/open-responses/blob/main/src/main/kotlin/ai/masaic/openresponses/tool/mcp/MCPToolModels.kt"
    click Models "https://github.com/masaic-ai-platform/open-responses/blob/main/src/main/kotlin/ai/masaic/openresponses/api/model/Models.kt"
    click Tests "https://github.com/masaic-ai-platform/open-responses/tree/main/src/test/kotlin/ai/masaic/openresponses"
```
