# openai/openai-realtime-solar-system architecture

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

- Interactive diagram: https://gitdiagram.com/openai/openai-realtime-solar-system
- Repository: https://github.com/openai/openai-realtime-solar-system

## Overview

##### Main Components
- Frontend UI: Represented by the NextJS app/page.tsx, layout.tsx in the app directory, and the various React components under the components folder (e.g., scene.tsx for rendering the 3D scene, charts components for data visualizations, and controls for user interactions).
- API Endpoints: Under app/api, there are two endpoints:
- /api/iss (to fetch and display the ISS position)
- /api/session (to manage realtime sessions)
- Library/Configuration Layer: Found in the lib directory (config.ts, constants.ts, components-mapping.tsx). This layer defines behavior such as tool configuration, API keys, and interactions for function calling.
- External Services & Integrations:
- OpenAI Realtime API & WebRTC: Facilitates realtime function calling and voice interaction.
- Spline: Provides the 3D scene of the solar system and is integrated via the scene component (components/scene.tsx) by loading a remote Spline scene.

##### Relationships and Interactions
- The user's browser (client) loads the NextJS application.
- The UI is split into different components, where:
- The Scene component integrates with Spline to render the 3D solar system.
- Chart components display data (bar chart, pie chart) based on user queries.
- Control components handle interactive elements (like starting/stopping sessions or toggling the microphone).
- Voice commands and UI interactions trigger calls to API endpoints:
- The /api/session endpoint handles starting and stopping realtime sessions.
- The /api/iss endpoint fetches ISS related data.
- The lib/config.ts and lib/constants.ts file play key roles in mapping interactions (via OpenAI’s function-calling features) to appropriate actions in the UI, such as focusing on planets, showing orbits, triggering animations, etc.

##### Architectural Patterns and Technologies
- The project uses a modern React/NextJS architecture, separating presentation (UI components) and business logic (API endpoints and configuration libraries).
- It leverages event-driven integrations via the OpenAI Realtime API and WebRTC for realtime updates.
- The use of external 3D rendering through Spline introduces an integration pattern where browser-based rendering and external events are coordinated.
- The API endpoints illustrate a RESTful design pattern, encapsulated within the NextJS App Router.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Nodes
    A["Client Browser"]:::external

    %% Frontend UI Subgraph
    subgraph "NextJS Frontend"
        FL["Main Layout & Pages (NextJS)"]:::ui
        SC["3D Scene Component (Spline Scene)"]:::ui
        CH["Charts Components"]:::ui
        CT["Controls Component"]:::ui
    end

    %% API Layer Subgraph
    subgraph "API Layer"
        API_ISS["/api/iss (ISS Data)"]:::api
        API_SESSION["/api/session (Session Management)"]:::api
    end

    %% Library/Configuration Layer
    LC["Library/Configuration Layer"]:::lib

    %% External Integrations Subgraph
    subgraph "External Integrations"
        OPENAI["OpenAI Realtime API & WebRTC"]:::external
        SPLINE["Spline 3D Service"]:::external
    end

    %% Supportive Tools
    BT["Styling & Build Tools (Tailwind, PostCSS, ESLint)"]:::tool

    %% Connections
    A -->|"loads"| FL
    FL -->|"renders"| SC
    FL -->|"renders"| CH
    FL -->|"renders"| CT

    CT -->|"triggers_session"| API_SESSION
    CT -->|"triggers_iss"| API_ISS

    LC -->|"configures_UI"| FL
    LC -->|"configures_API"| API_SESSION
    LC -->|"configures_API"| API_ISS

    SC -->|"loads_scene"| SPLINE
    CT -->|"voice_command"| OPENAI

    OPENAI -->|"informs"| LC

    BT --- FL

    %% Click Events
    click FL "https://github.com/openai/openai-realtime-solar-system/blob/main/app/layout.tsx"
    click FL "https://github.com/openai/openai-realtime-solar-system/blob/main/app/page.tsx"
    click SC "https://github.com/openai/openai-realtime-solar-system/blob/main/components/scene.tsx"
    click SC "https://github.com/openai/openai-realtime-solar-system/blob/main/components/scene.css"
    click CH "https://github.com/openai/openai-realtime-solar-system/blob/main/components/charts/chart.tsx"
    click CH "https://github.com/openai/openai-realtime-solar-system/blob/main/components/charts/pie-chart.tsx"
    click CT "https://github.com/openai/openai-realtime-solar-system/blob/main/components/controls.tsx"
    click API_ISS "https://github.com/openai/openai-realtime-solar-system/blob/main/app/api/iss/route.ts"
    click API_SESSION "https://github.com/openai/openai-realtime-solar-system/blob/main/app/api/session/route.ts"
    click LC "https://github.com/openai/openai-realtime-solar-system/blob/main/lib/config.ts"

    %% Styles
    classDef ui fill:#f9c,stroke:#333,stroke-width:2px;
    classDef api fill:#afa,stroke:#333,stroke-width:2px;
    classDef lib fill:#ff9,stroke:#333,stroke-width:2px;
    classDef external fill:#9cf,stroke:#333,stroke-width:2px;
    classDef tool fill:#ccc,stroke:#333,stroke-width:2px;
```
