# tyumu/roamloid architecture

> Architecture diagram of the GitHub repository tyumu/roamloid, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tyumu/roamloid
- Repository: https://github.com/tyumu/roamloid

## Overview

##### Project type and purpose
- This is a full-stack learning project whose focus is on real-time communication, authentication, 3D rendering, and AI-driven chat.
- The frontend is a React/TypeScript application built with Vite and React Three Fiber.
- The backend (in a separate Flask repo) provides REST endpoints for authentication and uses Socket.IO for real-time events.
- It integrates with an external AI service (Gemini API) for chat generation.

##### File structure
- Top-level directories:
- public: static assets (GLB character models and animations)
- src: application source (components, hooks, pages, routes, utils)
- test: end-to-end and static tests (REST, HTML/JS demos)
- Key config files:
- vite.config.ts & tsconfig.json (build & TS config)
- .env.example & .env.development (environment variables for API URL and CORS)
- .github/workflows/backend-ci.yml (CI for backend tests)
- Patterns:
- Component-based UI with React Three Fiber for 3D
- Custom hooks for WebSocket management and warp controls
- ProtectedRoute for guarding authenticated pages
- Utils/api.ts wrapping Axios for REST calls

##### README for additional insights
- Clear table of supported features (realtime connect, auth, 3D rendering, AI chat)
- API surface: HTTP endpoints under /api/auth and /api/room/devices, plus WS events (join_room, send_data, receive_data, moved_3d)
- Startup instructions illustrate two independent services (frontend on 5173, backend on 5000)

##### Detail without overthinking
- Every major component (UI shells, 3D renderer, REST client, WS client, API controllers, AI adapter, DB).
- How data flows end-to-end: user action → REST/WS call → backend logic → response → UI update.
- Extensibility points (where you'd swap AI service, add new WS events or new page routes).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Client" 
        direction TB
        subgraph "UI Components"
            direction TB
            CM["CharacterModel"]:::frontend
            WP["WarpParticles"]:::frontend
            CO["ChatOverlay"]:::frontend
            CLP["ChatLogPanel"]:::frontend
            ASB["AiStatusBadge"]:::frontend
            DM["DebugMenu"]:::frontend
        end
        subgraph "Custom Hooks"
            direction TB
            SM["useSocketManager"]:::utility
            WC["useWarpControl"]:::utility
        end
        subgraph "Pages"
            direction TB
            LP["Login Page"]:::frontend
            RP["Register Page"]:::frontend
            DSP["DeviceSelection Page"]:::frontend
        end
        subgraph "Routing"
            direction TB
            AR["AppRoutes"]:::frontend
            PR["ProtectedRoute"]:::frontend
        end
        subgraph "Network Layer"
            direction TB
            API["REST API Wrapper (api.ts)"]:::utility
            AIS["AI Samples Utility"]:::utility
            WS["WebSocket Client"]:::utility
        end
        subgraph "Configuration"
            direction TB
            VC["vite.config.ts"]:::utility
            TC["tsconfig.json"]:::utility
            EV[".env.example"]:::utility
        end
        PAS["Public Asset Store\n(models)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Server"
        direction TB
        subgraph "API Layer"
            direction TB
            AuthC["AuthController"]:::backend
            DeviceC["DeviceController"]:::backend
        end
        subgraph "WebSocket Layer"
            direction TB
            Socket["Socket.IO Server"]:::backend
        end
        subgraph "Business Logic"
            direction TB
            AIAdapter["AI Adapter"]:::backend
        end
        DB["Database"]:::db
    end

    %% External Service
    EAI["External AI Service\n(Gemini API)"]:::external

    %% Relationships
    LP -->|navigates| AR
    RP -->|navigates| AR
    DSP -->|navigates| AR
    AR -->|guards| PR
    LP -->|uses| API
    RP -->|uses| API
    DSP -->|uses| API
    CM -->|renders| PAS
    WP -->|renders| PAS
    CM -->|uses hook| SM
    WP -->|uses hook| WC
    SM -->|connects| WS
    WS -->|WS events| Socket
    API -->|HTTP| AuthC
    API -->|HTTP| DeviceC
    Socket -->|events| AIAdapter
    AuthC -->|queries| DB
    DeviceC -->|queries| DB
    AIAdapter -->|HTTP| EAI

    API -->|calls| AIS

    %% Click Events
    click CM "https://github.com/tyumu/roamloid/blob/main/src/components/CharacterModel.tsx"
    click WP "https://github.com/tyumu/roamloid/blob/main/src/components/WarpParticles.tsx"
    click CO "https://github.com/tyumu/roamloid/blob/main/src/components/ChatOverlay.tsx"
    click CLP "https://github.com/tyumu/roamloid/blob/main/src/components/ChatLogPanel.tsx"
    click ASB "https://github.com/tyumu/roamloid/blob/main/src/components/AiStatusBadge.tsx"
    click DM "https://github.com/tyumu/roamloid/blob/main/src/components/DebugMenu.tsx"
    click SM "https://github.com/tyumu/roamloid/blob/main/src/hooks/useSocketManager.ts"
    click WC "https://github.com/tyumu/roamloid/blob/main/src/hooks/useWarpControl.ts"
    click LP "https://github.com/tyumu/roamloid/blob/main/src/pages/Login.tsx"
    click RP "https://github.com/tyumu/roamloid/blob/main/src/pages/Register.tsx"
    click DSP "https://github.com/tyumu/roamloid/blob/main/src/pages/DeviceSelection.tsx"
    click AR "https://github.com/tyumu/roamloid/blob/main/src/routes/AppRoutes.tsx"
    click PR "https://github.com/tyumu/roamloid/blob/main/src/routes/ProtectedRoute.tsx"
    click API "https://github.com/tyumu/roamloid/blob/main/src/utils/api.ts"
    click AIS "https://github.com/tyumu/roamloid/blob/main/src/utils/aisamples.ts"
    click VC "https://github.com/tyumu/roamloid/blob/main/vite.config.ts"
    click TC "https://github.com/tyumu/roamloid/blob/main/tsconfig.json"
    click EV "https://github.com/tyumu/roamloid/blob/main/.env.example"
    click PAS "https://github.com/tyumu/roamloid/tree/main/public/models/character/"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#000
    classDef backend fill:#d4edda,stroke:#000
    classDef external fill:#fff3cd,stroke:#000
    classDef db fill:#f8d7da,stroke:#000
    classDef utility fill:#e2e3e5,stroke:#000

    class CM,WP,CO,CLP,ASB,DM,LP,RP,DSP,AR,PR,PAS frontend
    class AuthC,DeviceC,Socket,AIAdapter backend
    class EAI external
    class DB db
    class SM,WC,API,AIS,VC,TC,EV,WS utility
```
