# openai/openai-support-agent-demo architecture

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

- Interactive diagram: https://gitdiagram.com/openai/openai-support-agent-demo
- Repository: https://github.com/openai/openai-support-agent-demo

## Overview

##### Project type and purpose
- This is a full-stack Next.js demo application called “Customer Support Agent with Human in the Loop.”
- It provides two UIs (customer and agent), a set of REST-style API endpoints, business logic for orchestrating AI calls, and integrations with OpenAI’s Responses API and vector store (file search).

##### File structure
- Top-level directories:
– app/ – Next.js App Router: React pages (UI) and serverless API routes under app/api
– components/ – Reusable React components for chat, panels, tool calls, etc.
– config/ – Configuration for prompts, demo data, function definitions, tool listings
– lib/ – Core logic for the AI assistant, tool invocation, utilities
– stores/ – Client-side state management (Zustand hooks)
– public/ – Static assets: FAQ and knowledge base markdown, images
- Key patterns:
– API layer: each resource (orders, tickets, users, vector_stores, etc.) lives under app/api
– Business logic separated into config/functions.ts and lib/tools
– Frontend UI split between app pages and components/ui sub-folder
- Configuration and build files: next.config.mjs, tsconfig.json, tailwind.config.ts, package.json

##### README for additional insights
- Describes AI-enabled features: multi-turn chat, function calling, streaming, suggested actions, vector store file search
- Specifies “Human in the Loop” flow: AI proposes responses/actions, human agent confirms
- Notes customization points: config/constants.ts, config/tools-list.ts, config/functions.ts, config/demoData.ts, and own backend endpoints

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Client)" 
        direction TB
        CustomerUI["Customer UI"]:::frontend
        click CustomerUI "https://github.com/openai/openai-support-agent-demo/blob/main/app/page.tsx"
        CustomerKB["Knowledge Base Page"]:::frontend
        click CustomerKB "https://github.com/openai/openai-support-agent-demo/blob/main/app/kb/page.tsx"
        CustomerFAQ["FAQ Page"]:::frontend
        click CustomerFAQ "https://github.com/openai/openai-support-agent-demo/blob/main/app/faq/page.tsx"
        AgentUI["Agent UI"]:::frontend
        click AgentUI "https://github.com/openai/openai-support-agent-demo/blob/main/app/page.tsx"
        SharedUI["Shared UI Components"]:::frontend
        click SharedUI "https://github.com/openai/openai-support-agent-demo/blob/main/components/ui/button.tsx"
        StateStore["Client State Stores"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Next.js)" 
        direction TB
        %% API Routes
        subgraph "API Layer – Customer Support Resources"
            direction TB
            OrdersAPI["Orders API"]:::backend
            click OrdersAPI "https://github.com/openai/openai-support-agent-demo/blob/main/app/api/orders/[order_id]/route.ts"
            CancelAPI["Cancel Order API"]:::backend
            click CancelAPI "https://github.com/openai/openai-support-agent-demo/blob/main/app/api/orders/[order_id]/cancel/route.ts"
            RefundAPI["Create Refund API"]:::backend
            click RefundAPI "https://github.com/openai/openai-support-agent-demo/blob/main/app/api/orders/[order_id]/create_refund/route.ts"
            ReturnAPI["Create Return API"]:::backend
            click ReturnAPI "https://github.com/openai/openai-support-agent-demo/blob/main/app/api/orders/[order_id]/create_return/route.ts"
            ReplacementAPI["Send Replacement API"]:::backend
            click ReplacementAPI "https://github.com/openai/openai-support-agent-demo/blob/main/app/api/orders/[order_id]/send_replacement/route.ts"
            TicketsAPI["Create Ticket API"]:::backend
            click TicketsAPI "https://github.com/openai/openai-support-agent-demo/blob/main/app/api/tickets/create/route.ts"
            ComplaintsAPI["Create Complaint API"]:::backend
            click ComplaintsAPI "https://github.com/openai/openai-support-agent-demo/blob/main/app/api/complaints/create/route.ts"
            UsersHistoryAPI["User Order History API"]:::backend
            click UsersHistoryAPI "https://github.com/openai/openai-support-agent-demo/blob/main/app/api/users/[user_id]/order_history/route.ts"
            UsersResetAPI["User Reset Password API"]:::backend
            click UsersResetAPI "https://github.com/openai/openai-support-agent-demo/blob/main/app/api/users/[user_id]/reset_password/route.ts"
            UsersUpdateAPI["User Update Info API"]:::backend
            click UsersUpdateAPI "https://github.com/openai/openai-support-agent-demo/blob/main/app/api/users/[user_id]/update_info/route.ts"
            VouchersAPI["Create Voucher API"]:::backend
            click VouchersAPI "https://github.com/openai/openai-support-agent-demo/blob/main/app/api/vouchers/create/route.ts"
            TurnResponseAPI["Turn Response API"]:::backend
            click TurnResponseAPI "https://github.com/openai/openai-support-agent-demo/blob/main/app/api/turn_response/route.ts"
        end

        subgraph "API Layer – Vector Store & File Search"
            direction TB
            VSCreate["Create Store API"]:::backend
            click VSCreate "https://github.com/openai/openai-support-agent-demo/blob/main/app/api/vector_stores/create_store/route.ts"
            VSAddFile["Add File API"]:::backend
            click VSAddFile "https://github.com/openai/openai-support-agent-demo/blob/main/app/api/vector_stores/add_file/route.ts"
            VSUpload["Upload File API"]:::backend
            click VSUpload "https://github.com/openai/openai-support-agent-demo/blob/main/app/api/vector_stores/upload_file/route.ts"
            VSListFiles["List Files API"]:::backend
            click VSListFiles "https://github.com/openai/openai-support-agent-demo/blob/main/app/api/vector_stores/list_files/route.ts"
            VSGetFile["Get File API"]:::backend
            click VSGetFile "https://github.com/openai/openai-support-agent-demo/blob/main/app/api/vector_stores/get_file/route.ts"
            VSRetrieve["Retrieve Store API"]:::backend
            click VSRetrieve "https://github.com/openai/openai-support-agent-demo/blob/main/app/api/vector_stores/retrieve_store/route.ts"
            ListFilesAPI["General List Files API"]:::backend
            click ListFilesAPI "https://github.com/openai/openai-support-agent-demo/blob/main/app/api/list_files/route.ts"
        end

        VSInitPage["Vector Store Init Page"]:::backend
        click VSInitPage "https://github.com/openai/openai-support-agent-demo/blob/main/app/init_vs/page.tsx"

        subgraph "Business Logic"
            direction TB
            Assistant["AI Assistant Service"]:::backend
            click Assistant "https://github.com/openai/openai-support-agent-demo/blob/main/lib/assistant.ts"
            Tools["Tool Definitions"]:::backend
            click Tools "https://github.com/openai/openai-support-agent-demo/blob/main/lib/tools/tools.ts"
            ToolHandler["Tool Handling"]:::backend
            click ToolHandler "https://github.com/openai/openai-support-agent-demo/blob/main/lib/tools/tools-handling.ts"
            Utils["Utilities"]:::backend
            click Utils "https://github.com/openai/openai-support-agent-demo/blob/main/lib/utils.ts"
            ConfigConstants["Config Constants"]:::backend
            click ConfigConstants "https://github.com/openai/openai-support-agent-demo/blob/main/config/constants.ts"
            ConfigFunctions["Function Definitions"]:::backend
            click ConfigFunctions "https://github.com/openai/openai-support-agent-demo/blob/main/config/functions.ts"
            ConfigToolsList["Tools List"]:::backend
            click ConfigToolsList "https://github.com/openai/openai-support-agent-demo/blob/main/config/tools-list.ts"
            ConfigDemo["Demo Data"]:::backend
            click ConfigDemo "https://github.com/openai/openai-support-agent-demo/blob/main/config/demoData.ts"
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAIChat["OpenAI Responses API"]:::external
        VectorStoreService["OpenAI Vector Store API"]:::external
    end

    %% Static Content
    subgraph "Static Content"
        direction TB
        KBMarkdown["Knowledge Base Markdown"]:::static
        FAQMarkdown["FAQ Markdown"]:::static
    end

    %% Connections
    CustomerUI -->|"HTTP Requests"| OrdersAPI
    CustomerUI --> TicketsAPI
    CustomerUI --> ComplaintsAPI
    CustomerUI --> UsersHistoryAPI
    CustomerUI --> VouchersAPI
    AgentUI --> OrdersAPI
    AgentUI --> TurnResponseAPI
    SharedUI --> OrdersAPI
    StateStore --> OrdersAPI

    OrdersAPI --> Assistant
    CancelAPI --> Assistant
    RefundAPI --> Assistant
    ReturnAPI --> Assistant
    ReplacementAPI --> Assistant
    TicketsAPI --> Assistant
    ComplaintsAPI --> Assistant
    UsersHistoryAPI --> Assistant
    UsersResetAPI --> Assistant
    UsersUpdateAPI --> Assistant
    VouchersAPI --> Assistant
    TurnResponseAPI --> Assistant

    VSCreate --> Assistant
    VSAddFile --> Assistant
    VSUpload --> Assistant
    VSListFiles --> Assistant
    VSGetFile --> Assistant
    VSRetrieve --> Assistant
    ListFilesAPI --> Assistant

    VSInitPage --> VSCreate
    VSInitPage --> VSAddFile
    VSInitPage --> VSUpload

    Assistant -->|"Calls"| OpenAIChat
    Assistant -->|"Searches"| VectorStoreService
    Assistant --> ConfigDemo

    KBMarkdown -->|"Served as static"| CustomerKB
    FAQMarkdown -->|"Served as static"| CustomerFAQ

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef backend fill:#DDF4DD,stroke:#22863A,color:#22863A
    classDef external fill:#FFF5B1,stroke:#DBAB09,color:#735C0F
    classDef static fill:#F0F0F0,stroke:#6A737D,color:#6A737D
```
