# chirag2483/sparkathon_loners architecture

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

- Interactive diagram: https://gitdiagram.com/chirag2483/sparkathon_loners
- Repository: https://github.com/chirag2483/sparkathon_loners

## Overview

##### Project Type & Purpose
- Meesho-verse AI is a full-stack Meta-Commerce platform delivering an immersive 3D shopping experience in a browser.
- It consists of a rich frontend (Three.js, WebRTC, Socket.IO, computer vision) and a Node.js/Express.js backend handling static assets, REST endpoints, and real-time events.

##### File-Structure Analysis
- Top-level “client/” folder: HTML pages, CSS, JS libs (Three.js, loaders), assets (models, textures), and a “src/” subfolder organized by feature (character, env, shop, tryon, video).
- “server/” folder: Node.js server.js (Express + Socket.IO + CORS), room-server.js (WebRTC/Socket signaling), plus install scripts and package.json.
- No standalone database folder—room state appears in-memory or ephemeral; AI calls originate from the client via ai-config.

##### Key Components
a. Frontend (Client)
- Static Web Server (serves HTML/CSS/JS)
- Three.js Renderer & 3D Scene Graph
- Virtual Try-On Module (WebRTC camera + face-tracking + computer vision)
- UI Components (character selector, shop interface)
- Real-time Collaboration Module (Socket.IO client + WebRTC media streams)
- AI Assistant Client (fetches from external AI APIs)

b. Backend (Server)
- Express.js HTTP API (serves static content, REST endpoints: /api/rooms, /api/rooms/:code, etc.)
- Socket.IO Server (events: join-room, share-product, chat-message, etc.)
- room-server.js (WebRTC signaling for lobby/room RTC)
- Configurable CORS layer

c. External Services
- AI Service Providers (OpenRouter, OpenAI, Claude, Cohere, Hugging Face)
- (Optional) Reverse Proxy / Load Balancer (Nginx)
- (Optional) Process Manager (PM2)

##### Component Interactions & Data Flows
- Browser requests static assets via HTTP GET → Express.js
- User actions (join room, share product, chat) emit Socket.IO messages to Socket.IO Server
- Socket.IO Server relays real-time events to other clients in the same room
- WebRTC negotiation & media streams use room-server.js as a signaling intermediary
- Virtual Try-On module captures camera feed → local processing → overlays 3D garments
- AI Assistant UI sends REST/Fetch to external AI APIs (through client-side ai-config.js)
- Checkout/Order operations occur via REST endpoints (if extended to a database)

##### Architectural Patterns & Principles
- Modular Frontend by feature (character, env, shop, tryon, video)
- Separation of Concerns: Static content vs. real-time events vs. AI calls
- Event-Driven Communication (Socket.IO) for low-latency collaboration
- Externalized AI logic—keeping API keys/config in ai-config.js and environment variables
- Progressive Enhancement—fallbacks for camera/microphone permissions

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients and Browsers
    subgraph "Client App" 
        direction TB
        Browser["User Browser"]:::external

        subgraph "3D Engine" 
            direction TB
            ThreeLib["Core Three.js Library"]:::frontend
            LoaderUtils["Loader Utilities"]:::frontend
            SceneMgr["3D Scene Management"]:::frontend
            Renderer["Three.js Renderer & Scene Graph"]:::frontend
        end

        subgraph "Virtual Try-On" 
            direction TB
            CameraCap["Camera Capture"]:::frontend
            CLMTrack["Face-Tracking Library"]:::frontend
            TryOnCore["Virtual Try-On Module"]:::frontend
            TryOnEnh["Enhanced Try-On Pipeline"]:::frontend
            TryOnUtils["Try-On Utilities"]:::frontend
        end

        subgraph "UI Components"
            direction TB
            HomeUI["Home & Lobby Screens"]:::frontend
            CharSel["Character Selector UI"]:::frontend
            ShopUI["Shop Interface UI"]:::frontend
            ShopLoad["Shop Loader"]:::frontend
        end

        subgraph "Collaboration"
            direction TB
            SocketClient["Socket.IO Client Utilities"]:::frontend
            Controllers["Client Controllers"]:::frontend
            VideoRTC["WebRTC Video Module"]:::frontend
            VideoScripts["Video Lobby & Room Scripts"]:::frontend
        end

        subgraph "AI Assistant"
            direction TB
            AIConfig["AI Assistant Configuration"]:::frontend
            Chatbot["Chatbot Frontend Logic"]:::frontend
        end

        Assets["3D Models & Textures"]:::frontend
    end

    subgraph "Server Cluster"
        direction TB
        Express["Express.js HTTP API\n(Static & REST)"]:::backend
        SocketServer["Socket.IO Server"]:::backend
        Signaling["WebRTC Signaling Server"]:::backend
        CORS["CORS Configuration"]:::backend
    end

    subgraph "External Services"
        direction TB
        AICloud["AI Service Providers"]:::external
        P2P["Peer Browsers (WebRTC)"]:::external
    end

    %% Data Flows
    Browser -->|"HTTP GET"| Express
    Browser -->|"WS Events"| SocketServer
    Browser -->|"RTC Signaling"| Signaling
    Signaling -->|"Peer Negotiation"| P2P
    VideoRTC <-->|"Media Streams"| P2P
    TryOnCore -->|"Overlay Textures"| Renderer
    CameraCap --> CLMTrack
    CLMTrack --> TryOnCore
    AIConfig -->|"REST Call"| AICloud
    Chatbot --> AIConfig
    SocketClient -->|"emit/join-room"| SocketServer
    SocketClient -->|"on/events"| SocketServer
    HomeUI --> SocketClient
    CharSel --> SceneMgr
    ShopUI --> ShopLoad
    ShopLoad --> SceneMgr
    LoaderUtils --> SceneMgr
    ThreeLib --> Renderer
    SceneMgr --> Renderer
    Assets --> LoaderUtils
    Controllers --> SocketClient
    VideoScripts --> VideoRTC

    %% Click Events
    click Express "https://github.com/chirag2483/sparkathon_loners/blob/main/Meesho-verse/server/server.js"
    click SocketServer "https://github.com/chirag2483/sparkathon_loners/blob/main/Meesho-verse/server/server.js"
    click CORS "https://github.com/chirag2483/sparkathon_loners/blob/main/Meesho-verse/server/server.js"
    click Signaling "https://github.com/chirag2483/sparkathon_loners/blob/main/Meesho-verse/server/room-server.js"
    click ThreeLib "https://github.com/chirag2483/sparkathon_loners/blob/main/Meesho-verse/client/js/three.js"
    click LoaderUtils "https://github.com/chirag2483/sparkathon_loners/blob/main/Meesho-verse/client/js/LoaderUtils.js"
    click SceneMgr "https://github.com/chirag2483/sparkathon_loners/blob/main/Meesho-verse/client/src/env/Scene.js"
    click Renderer "https://github.com/chirag2483/sparkathon_loners/blob/main/Meesho-verse/client/src/env/Renderer.js"
    click TryOnCore "https://github.com/chirag2483/sparkathon_loners/blob/main/Meesho-verse/client/src/tryon/tryon.js"
    click TryOnEnh "https://github.com/chirag2483/sparkathon_loners/blob/main/Meesho-verse/client/src/tryon/tryon-enhanced.js"
    click TryOnUtils "https://github.com/chirag2483/sparkathon_loners/blob/main/Meesho-verse/client/src/tryon/utils.js"
    click CLMTrack "https://github.com/chirag2483/sparkathon_loners/blob/main/Meesho-verse/client/js/clmtrackr.js"
    click CharSel "https://github.com/chirag2483/sparkathon_loners/blob/main/Meesho-verse/client/src/character/character-selector/CharacterSelector.js"
    click ShopUI "https://github.com/chirag2483/sparkathon_loners/blob/main/Meesho-verse/client/src/shop/shop.js"
    click ShopLoad "https://github.com/chirag2483/sparkathon_loners/blob/main/Meesho-verse/client/src/shop/loadShop.js"
    click HomeUI "https://github.com/chirag2483/sparkathon_loners/blob/main/Meesho-verse/client/src/UI/HomeScreen.js"
    click SocketClient "https://github.com/chirag2483/sparkathon_loners/blob/main/Meesho-verse/client/src/Utils/sockets.js"
    click Controllers "https://github.com/chirag2483/sparkathon_loners/blob/main/Meesho-verse/client/js/controllers.js"
    click AIConfig "https://github.com/chirag2483/sparkathon_loners/blob/main/Meesho-verse/client/js/ai-config.js"
    click Chatbot "https://github.com/chirag2483/sparkathon_loners/blob/main/Meesho-verse/client/js/chatbot.js"
    click VideoRTC "https://github.com/chirag2483/sparkathon_loners/blob/main/Meesho-verse/client/src/video/room_rtc.js"
    click VideoScripts "https://github.com/chirag2483/sparkathon_loners/blob/main/Meesho-verse/client/src/video/lobby.js"
    click VideoScripts "https://github.com/chirag2483/sparkathon_loners/blob/main/Meesho-verse/client/src/video/room.js"
    click Assets "https://github.com/chirag2483/sparkathon_loners/tree/main/Meesho-verse/client/assets/models"
    click Assets "https://github.com/chirag2483/sparkathon_loners/tree/main/Meesho-verse/client/assets/textures"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1F618D,color:#1F618D;
    classDef backend fill:#A9DFBF,stroke:#229954,color:#145A32;
    classDef external fill:#F9E79F,stroke:#B7950B,color:#7D6608;
```
