# openai/openai-responses-starter-app architecture

> Architecture diagram of the GitHub repository openai/openai-responses-starter-app, 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/openai/openai-responses-starter-app
- Repository: https://github.com/openai/openai-responses-starter-app

## Overview

##### Project Type and Purpose
- This is a full-stack Next.js application (“Responses starter app”) providing a chat interface powered by the OpenAI Responses API.
- It implements multi-turn conversations, built-in tools (web search, file search via vector stores), function calling, streaming, and annotations.

##### File Structure Analysis
- Top-level “app” directory follows Next.js App Router conventions, containing:
- app/page.tsx & app/layout.tsx – client-rendered React pages & layouts
- app/api – serverless route handlers (functions for jokes, weather, OpenAI turn responses, vector store operations)
- “components” – reusable UI components (chat view, panels, inputs, tool selectors) plus a subfolder “ui” for primitives (button, dialog, tooltip, etc.)
- “lib” – business logic, wrapping the OpenAI Responses SDK (assistant.ts) and tool-handling code
- “config” – configuration of functions, tools list, constants
- “stores” – Zustand hooks for client state (useConversationStore, useToolsStore)
- Public/static assets under “public”, styling with Tailwind (tailwind.config.ts, globals.css)
- Standard config & build scripts (package.json, tsconfig.json, next.config.mjs, ESLint, PostCSS)

##### Key README Insights
- Purpose: Kick-start a conversational assistant using the Responses API
- Highlights: web search, file search via vector stores, function calling, streaming responses
- Usage: client obtains API key, runs Next.js dev server

##### Main System Components
a. Client Browser (React SPA)
- Components: Chat UI, Tool Panels, File Upload & Search UI, State Stores
b. Next.js Server (App Router)
- API Routes (serverless functions):
- get_joke, get_weather – simple demo endpoints
- turn_response – orchestrates calls to OpenAI Responses API
- vector_stores/* – create/retrieve stores, upload files, list files
c. Business Logic Layer (lib/)
- assistant.ts: OpenAI Responses API wrapper
- tools-handling.ts: dispatches function calls & tool use
d. External Services
- OpenAI Responses API
- Web Search tool endpoint
- (Optional) Vector store backend (e.g., internal or third-party service)

##### Component Interactions & Data Flow
- User types message → Frontend state store updates → Frontend invokes turn_response API →
- Serverless turn_response route calls assistant.ts → Streams data back to client →
- If a tool is invoked, tool-handlers route calls to web search or vector store endpoints → Results return to assistant → Combined response streams back to client
- Frontend renders messages, annotations, tool outputs

##### Architectural Patterns & Principles
- Separation of Concerns: UI vs. API vs. business logic
- Serverless micro-endpoints under Next.js App Router
- Custom hooks for client state (Zustand)
- Config-driven tool & function definitions
- Streaming & incremental rendering

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Browser Zone
    subgraph "Client Browser"
        direction TB
        Layout["Page Layout"]:::frontend
        Page["Main Page (Chat)"]:::frontend
        ChatUI["Chat UI"]:::frontend
        ToolsPanel["Tools Panel UI"]:::frontend
        FileUpload["File Upload UI"]:::frontend
        FileSearchUI["File Search Setup UI"]:::frontend
        subgraph "State Stores"
            direction TB
            ConvStore["Conversation State Store"]:::state
            ToolsStore["Tools State Store"]:::state
        end
    end

    %% Server Zone
    subgraph "Next.js Server"
        direction TB
        subgraph "API Routes"
            direction TB
            GetJoke["get_joke API"]:::api
            GetWeather["get_weather API"]:::api
            TurnResponse["turn_response API"]:::api
            subgraph "Vector Stores"
                direction TB
                CreateStore["create_store"]:::api
                RetrieveStore["retrieve_store"]:::api
                ListFiles["list_files"]:::api
                AddFile["add_file"]:::api
                UploadFile["upload_file"]:::api
            end
        end

        subgraph "Business Logic"
            direction TB
            Assistant["OpenAI Wrapper"]:::logic
            ToolsLogic["Tools Dispatch Logic"]:::logic
            ToolsDef["Tool Definitions"]:::logic
        end

        subgraph "Config"
            direction TB
            FuncConfig["functions.ts"]:::config
            ToolsConfig["tools-list.ts"]:::config
            ConstConfig["constants.ts"]:::config
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI Responses API"]:::external
        WebSearch["Web Search Tool"]:::external
        VectorService["Vector Store Service"]:::external
    end

    %% Connections: Client -> Server
    ChatUI -->|"POST /api/turn_response"| TurnResponse
    ToolsPanel -->|"GET /api/functions/get_joke"| GetJoke
    ToolsPanel -->|"GET /api/functions/get_weather"| GetWeather
    FileUpload -->|"upload file request"| UploadFile
    FileUpload -->|"add file request"| AddFile
    FileSearchUI -->|"list files request"| ListFiles
    FileSearchUI -->|"retrieve store request"| RetrieveStore

    %% Server Internal flows
    TurnResponse -->|"calls"| Assistant
    Assistant -->|"invoke tools"| ToolsLogic
    ToolsLogic -->|"web search"| WebSearch
    ToolsLogic -->|"vector ops"| VectorService
    Assistant -->|"streaming response"| ChatUI

    %% Config influences
    FuncConfig --> GetJoke
    FuncConfig --> GetWeather
    FuncConfig --> TurnResponse
    ToolsConfig --> ToolsLogic
    ConstConfig --> Assistant

    %% Click Events
    click ChatUI "https://github.com/openai/openai-responses-starter-app/blob/main/components/chat.tsx"
    click ToolsPanel "https://github.com/openai/openai-responses-starter-app/blob/main/components/tools-panel.tsx"
    click FileUpload "https://github.com/openai/openai-responses-starter-app/blob/main/components/file-upload.tsx"
    click FileSearchUI "https://github.com/openai/openai-responses-starter-app/blob/main/components/file-search-setup.tsx"
    click Layout "https://github.com/openai/openai-responses-starter-app/blob/main/app/layout.tsx"
    click Page "https://github.com/openai/openai-responses-starter-app/blob/main/app/page.tsx"
    click ConvStore "https://github.com/openai/openai-responses-starter-app/blob/main/stores/useConversationStore.ts"
    click ToolsStore "https://github.com/openai/openai-responses-starter-app/blob/main/stores/useToolsStore.ts"
    click GetJoke "https://github.com/openai/openai-responses-starter-app/blob/main/app/api/functions/get_joke/route.ts"
    click GetWeather "https://github.com/openai/openai-responses-starter-app/blob/main/app/api/functions/get_weather/route.ts"
    click TurnResponse "https://github.com/openai/openai-responses-starter-app/blob/main/app/api/turn_response/route.ts"
    click CreateStore "https://github.com/openai/openai-responses-starter-app/blob/main/app/api/vector_stores/create_store/route.ts"
    click RetrieveStore "https://github.com/openai/openai-responses-starter-app/blob/main/app/api/vector_stores/retrieve_store/route.ts"
    click ListFiles "https://github.com/openai/openai-responses-starter-app/blob/main/app/api/vector_stores/list_files/route.ts"
    click AddFile "https://github.com/openai/openai-responses-starter-app/blob/main/app/api/vector_stores/add_file/route.ts"
    click UploadFile "https://github.com/openai/openai-responses-starter-app/blob/main/app/api/vector_stores/upload_file/route.ts"
    click Assistant "https://github.com/openai/openai-responses-starter-app/blob/main/lib/assistant.ts"
    click ToolsLogic "https://github.com/openai/openai-responses-starter-app/blob/main/lib/tools/tools-handling.ts"
    click ToolsDef "https://github.com/openai/openai-responses-starter-app/blob/main/lib/tools/tools.ts"
    click FuncConfig "https://github.com/openai/openai-responses-starter-app/blob/main/config/functions.ts"
    click ToolsConfig "https://github.com/openai/openai-responses-starter-app/blob/main/config/tools-list.ts"
    click ConstConfig "https://github.com/openai/openai-responses-starter-app/blob/main/config/constants.ts"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#005b99,color:#003366,stroke-width:1px
    classDef api fill:#d4edda,stroke:#155724,color:#0b2e13,stroke-width:1px
    classDef logic fill:#ffe5b4,stroke:#cc7a00,color:#663c00,stroke-width:1px
    classDef external fill:#f8d7da,stroke:#721c24,color:#491217,stroke-width:1px
    classDef state fill:#e2e3e5,stroke:#6c757d,color:#343a40,stroke-width:1px
    classDef config fill:#f5f5f5,stroke:#999999,color:#333333,stroke-width:1px
```
