# openai/openai-cs-agents-demo architecture

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

- Interactive diagram: https://gitdiagram.com/openai/openai-cs-agents-demo
- Repository: https://github.com/openai/openai-cs-agents-demo

## Overview

##### Main components
a. User (Web Browser)
b. Frontend (Next.js UI)
- app/pages (layout, page.tsx)
- components (Chat, agent-panel, seat-map, guardrails, etc.)
- lib/api.ts (REST client), types, utils
- TailwindCSS, postcss, Next config
c. Backend (Python service)
- api.py (FastAPI/UVicorn entrypoints)
- main.py (initialization)
- Agents Orchestrator (triage, seat-booking, flight-status, cancellation, FAQ)
- Guardrails module
- requirements.txt, python-dotenv for env vars
d. External Services
- OpenAI Agents SDK & OpenAI API endpoints
e. (Optional) Static Data / Assets
- UI public folder, seat-map data

##### Relationships and data flow
1. User types a message in the chat UI.
2. Frontend lib/api.ts issues HTTP POST to Python backend (e.g., http://localhost:8000/chat).
3. Python API endpoint receives request, loads OPENAI_API_KEY, and passes user input to the Agents Orchestrator.
4. Orchestrator uses the OpenAI Agents SDK:
- Triage Agent decides which specialist to invoke
- Calls relevant Agent (Seat Booking, Flight Status, Cancellation, FAQ)
- Applies Guardrails (Relevance, Jailbreak) at each step
5. Each Agent may call external “tools” or look up static data (e.g., seat-map).
6. SDK sends chat completion requests to the OpenAI API and receives responses.
7. Backend collates final response and guardrail flags, returns JSON to frontend.
8. Frontend UI renders messages, highlights guardrail trips, displays interactive seat map or other components.

##### Architectural patterns & design principles
- Layered separation: UI layer vs orchestration layer vs external services
- Modular agents: each Agent is a self-contained component (ease of extension)
- Single responsibility: Frontend only handles rendering & user I/O; Backend handles orchestration & API calls
- Stateless backend: relies on OpenAI and in-memory data, no persistent database

##### Relevant technologies & frameworks
- Next.js (React) with TypeScript, TailwindCSS
- FastAPI (via uvicorn) or equivalent in python-backend
- OpenAI Agents SDK & OpenAI REST API
- python-dotenv for environment variables

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Global entities
    User["User (Web Browser)"]

    %% Frontend Layer
    subgraph "Frontend (Next.js UI)"
        direction TB
        Pages["app/pages\n(layout.tsx, page.tsx)"]:::frontend
        Chat["Chat UI"]:::frontend
        AgentPanel["Agent Panel"]:::frontend
        AgentsList["Agents List"]:::frontend
        ConvContext["Conversation Context"]:::frontend
        GuardrailsDisplay["Guardrails Display"]:::frontend
        SeatMap["Seat Map"]:::frontend
        PanelSection["Panel Section"]:::frontend
        RunnerOutput["Runner Output"]:::frontend
        CommonUI["Common UI Elements"]:::frontend
        APIClient["REST Client\nlib/api.ts"]:::frontend
        Types["Type Definitions\nlib/types.ts"]:::frontend
        Utils["Utility Functions\nlib/utils.ts"]:::frontend
        Config["Next.js & TS Configs"]:::frontend
        Styling["Tailwind & PostCSS Configs"]:::frontend
        Assets["Static Assets\n(public)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Python Service)"
        direction TB
        API["api.py\n(FastAPI)"]:::backend
        Main["main.py\n(initialization)"]:::backend
        Requirements["requirements.txt\n(env deps)"]:::backend
        subgraph "Agents Orchestrator"
            direction TB
            Triage["Triage Agent"]:::backend
            SeatBooking["Seat Booking Agent"]:::backend
            FlightStatus["Flight Status Agent"]:::backend
            Cancellation["Cancellation Agent"]:::backend
            FAQ["FAQ Agent"]:::backend
            GuardrailsMod["Guardrails Module"]:::backend
        end
    end

    %% External Services
    External["OpenAI Agents SDK / API"]:::external

    %% Connections
    User -->|"interacts via UI"| Pages
    Pages -->|"uses API client"| APIClient
    APIClient -->|"POST /chat"| API
    API -->|"invoke orchestration"| Triage
    Triage -->|"route to specialist"| SeatBooking
    Triage -->|"route to specialist"| FlightStatus
    Triage -->|"route to specialist"| Cancellation
    Triage -->|"route to specialist"| FAQ
    SeatBooking -->|"apply guardrails"| GuardrailsMod
    FlightStatus -->|"apply guardrails"| GuardrailsMod
    Cancellation -->|"apply guardrails"| GuardrailsMod
    FAQ -->|"apply guardrails"| GuardrailsMod
    GuardrailsMod -->|"call OpenAI"| External
    SeatBooking -->|"call OpenAI"| External
    FlightStatus -->|"call OpenAI"| External
    Cancellation -->|"call OpenAI"| External
    FAQ -->|"call OpenAI"| External
    External -->|"response"| API
    API -->|"return JSON"| Pages
    Pages -->|"render UI"| User

    %% Click Events
    click Pages "https://github.com/openai/openai-cs-agents-demo/blob/main/ui/app/layout.tsx"
    click Pages "https://github.com/openai/openai-cs-agents-demo/blob/main/ui/app/page.tsx"
    click Chat "https://github.com/openai/openai-cs-agents-demo/blob/main/ui/components/Chat.tsx"
    click AgentPanel "https://github.com/openai/openai-cs-agents-demo/blob/main/ui/components/agent-panel.tsx"
    click AgentsList "https://github.com/openai/openai-cs-agents-demo/blob/main/ui/components/agents-list.tsx"
    click ConvContext "https://github.com/openai/openai-cs-agents-demo/blob/main/ui/components/conversation-context.tsx"
    click GuardrailsDisplay "https://github.com/openai/openai-cs-agents-demo/blob/main/ui/components/guardrails.tsx"
    click SeatMap "https://github.com/openai/openai-cs-agents-demo/blob/main/ui/components/seat-map.tsx"
    click PanelSection "https://github.com/openai/openai-cs-agents-demo/blob/main/ui/components/panel-section.tsx"
    click RunnerOutput "https://github.com/openai/openai-cs-agents-demo/blob/main/ui/components/runner-output.tsx"
    click CommonUI "https://github.com/openai/openai-cs-agents-demo/tree/main/ui/components/ui"
    click APIClient "https://github.com/openai/openai-cs-agents-demo/blob/main/ui/lib/api.ts"
    click Types "https://github.com/openai/openai-cs-agents-demo/blob/main/ui/lib/types.ts"
    click Utils "https://github.com/openai/openai-cs-agents-demo/blob/main/ui/lib/utils.ts"
    click Config "https://github.com/openai/openai-cs-agents-demo/blob/main/ui/next.config.mjs"
    click Styling "https://github.com/openai/openai-cs-agents-demo/blob/main/ui/tailwind.config.ts"
    click Assets "https://github.com/openai/openai-cs-agents-demo/tree/main/ui/public"
    click API "https://github.com/openai/openai-cs-agents-demo/blob/main/python-backend/api.py"
    click Main "https://github.com/openai/openai-cs-agents-demo/blob/main/python-backend/main.py"
    click Requirements "https://github.com/openai/openai-cs-agents-demo/blob/main/python-backend/requirements.txt"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#000
    classDef backend fill:#DFF2BF,stroke:#22863a,color:#000
    classDef external fill:#FFD8B0,stroke:#d15704,color:#000
```
