# haiderali780/ai-classroom-xr architecture

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

- Interactive diagram: https://gitdiagram.com/haiderali780/ai-classroom-xr
- Repository: https://github.com/haiderali780/ai-classroom-xr

## Overview

##### Project Type & Purpose
- The project is clearly a full-stack immersive 3D classroom application that leverages Three.js and React Three Fiber for the frontend, along with an Express.js-based proxy server to securely handle API requests to the OpenAI API.
- The focus is on creating an interactive 3D learning environment with an AI-powered teacher, incorporating advanced 3D models, realistic animations, and voice interactivity.

##### Analyzing the File Structure
- Top-level files include index.html and package.json (frontend entry points), indicating a React-based application.
- The “src” directory holds the main frontend code: components (like Experience.jsx, CameraManager.jsx, chat/Chat.jsx), styles (App.css, index.css), and assets – all contributing to the 3D scene and user interface.
- A “public” directory contains 3D models (GLB, JSX representations of models) suggesting that 3D assets are served at runtime.
- The separate “proxy-server” directory, with its own package.json, .env, and proxy.js file, represents the backend part. This server handles secure API interactions with the OpenAI API.
- Configuration files (like vite.config.js, .eslintrc.cjs) indicate build and development setups.

##### Key Components
a. Frontend Components:
- User Interface: Built using React and React Three Fiber, which renders the 3D classroom environment.
- Components:
- Main Scene Components (e.g., App.jsx, Experience.jsx) to manage the 3D scene.
- Interaction Components like Chat (chat/Chat.jsx, Chat.css) for conversation and chat history.
- Camera Management (CameraManager.jsx) to control user navigation in the 3D space.
- Assets & Models: 3D assets stored in the “public/models” folder (classroom and avatar models).

b. Backend Components:
- Express.js Proxy Server: Located in “proxy-server”, this component securely handles API calls to external services (i.e., the OpenAI API) and likely manages middleware (evidenced by the Express.js code in proxy.js) along with environment configurations.
- Environment & Configuration: The use of an .env file in the proxy-server provides necessary credentials and configuration for the API integration.

c. External Services:
- OpenAI API: Used for providing the AI-powered teacher functionality.
- Animation/3D Tools: Blender and Mixamo, which, although external to the runtime environment, are important for creating realistic models and animations.

##### Relationships & Data Flow
- User Interaction Flow: The user navigates the 3D classroom (via UI components in the React app) and interacts through chat (handled by Chat.jsx).
- API Requests: The React frontend sends conversational or speech triggers that are forwarded to the backend proxy server.
- Back-End Processing: The Express.js proxy processes these requests (using secure API keys from .env) and communicates with the OpenAI API.
- Feedback Loop: The response from the OpenAI API (delivered through the proxy) returns to the frontend, where the AI teacher’s text and voice responses update the user interface and chat history.

##### Architectural Patterns & Design Principles
- Separation of Concerns: The project clearly separates frontend (UI, 3D rendering, user interactions) and backend (secure API proxy) responsibilities.
- Modular Design: Each React component manages a distinct part of the application’s functionality (scene setup, camera handling, chat).
- Loose Coupling: The proxy server decouples the direct interaction with the OpenAI API from the client, enhancing security and maintainability.

– Begin by sketching two major sections: the Frontend and the Backend.
– Inside the Frontend block, detail the 3D scene components (Experience.jsx, CameraManager.jsx, Chat components) and link them to asset files (models in the “public/models” folder).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend"
        UI["React Frontend - 3D UI Components"]:::frontend
        subgraph "Components"
            A_App["App.jsx"]:::frontend
            A_Exp["Experience.jsx"]:::frontend
            A_Cam["CameraManager.jsx"]:::frontend
            A_Chat["Chat.jsx & Chat.css"]:::frontend
        end
        Models["3D Assets & Models"]:::assets
    end

    subgraph "Backend"
        Proxy["Express.js Proxy Server"]:::backend
        B_api["API Routing (proxy.js)"]:::backend
        B_conf["Configuration (.env)"]:::backend
    end

    subgraph "External Services"
        OpenAI["OpenAI API"]:::external
        Tools["3D Tools (Blender/Mixamo)"]:::external
    end

    subgraph "User Interaction"
        User["User"]:::user
    end

    User -->|"navigates"| UI
    UI -->|"renders3Dscene"| A_App
    UI --> A_Exp
    UI --> A_Cam
    UI --> A_Chat
    A_App -->|"loads"| Models
    A_Exp -->|"loads"| Models
    A_Chat -->|"sendsAPIrequest"| Proxy
    Proxy --> B_api
    Proxy --> B_conf
    B_api -->|"communicatesWith"| OpenAI
    OpenAI -->|"sendsResponse"| B_api
    Proxy -->|"returnsData"| A_Chat

    click A_App "https://github.com/haiderali780/ai-classroom-xr/blob/main/src/App.jsx"
    click A_Exp "https://github.com/haiderali780/ai-classroom-xr/blob/main/src/Experience.jsx"
    click A_Cam "https://github.com/haiderali780/ai-classroom-xr/blob/main/src/components/CameraManager.jsx"
    click A_Chat "https://github.com/haiderali780/ai-classroom-xr/blob/main/src/components/chat/Chat.jsx"
    click Models "https://github.com/haiderali780/ai-classroom-xr/tree/main/public/models"
    click B_api "https://github.com/haiderali780/ai-classroom-xr/blob/main/proxy-server/proxy.js"
    click B_conf "https://github.com/haiderali780/ai-classroom-xr/blob/main/proxy-server/.env"

    classDef frontend fill:#b3d9ff,stroke:#3399ff,stroke-width:2px;
    classDef backend fill:#ffcccc,stroke:#ff6666,stroke-width:2px;
    classDef external fill:#ffffcc,stroke:#ffcc00,stroke-width:2px;
    classDef assets fill:#ccffcc,stroke:#33cc33,stroke-width:2px;
    classDef user fill:#f0e68c,stroke:#daa520,stroke-width:2px;
```
