# ayushmehre/padhai-assignment architecture

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

- Interactive diagram: https://gitdiagram.com/ayushmehre/padhai-assignment
- Repository: https://github.com/ayushmehre/padhai-assignment

## Overview

##### Project Type and Purpose
- This is a Proof-of-Concept full-stack (frontend + mock backend) application.
- Purpose: Render “interactable” geometry slides in the browser, detect and emit metadata for sub-elements, receive tutor commands over WebSockets (POINT, AUDIO, HIGHLIGHT), and apply them to the slide.

##### High-Level Components
a. Frontend Single-Page Application (SPA)
- Built with Vite + React + Tailwind CSS
- Core modules:
– App (main entry in src/main.jsx and App.jsx)
– TutorProvider (WebSocket connection, event bus via mitt, ring buffer)
– UI Components (buttons, inputs, switch, slider in src/components/ui)
– Custom Hooks (useInteractables, usePointerControl, useHighlighter, useAudioPlayer, useWebSocket, etc.)
– Utils/Lib (createRingBuffer, playBase64Audio)
- Static assets in public/ and src/assets
- Configs: socket.js, Tailwind, ESLint, TS configs, vite.config.ts

b. Mock Backend (mock-server/server.js)
- Node.js + ws library
- Accepts START_SESSION, then emits scripted POINT, HIGHLIGHT, AUDIO events over WebSocket

##### Relationships & Data Flows
- User clicks “Start” → UI Button (SlidePanel) emits START_SESSION to TutorProvider → WebSocket server
- Mock Server sends events → TutorProvider parses JSON → emits events on mitt event bus (stored in ring buffer)
- Components/Hooks subscribe:
- usePointerControl listens to POINT → moves cursor (DOM manipulations)
- useHighlighter listens to HIGHLIGHT → wraps or styles target text
- useAudioPlayer listens to AUDIO → streams/plays audio via playBase64Audio
- InteractableSlide: on mount or slide change, useInteractables queries DOM for data-role="interactable" → emits metadata JSON (boundingBox, id, type) back to TutorProvider → can forward to server or LLM

##### Architectural Patterns & Principles
- Event Bus Pattern (mitt) to decouple WebSocket layer from UI reaction
- Provider + React Context for global state (TutorContext)
- Custom Hooks for separation of concerns (pointer, audio, highlight, interactables)
- Ring Buffer for replaying recent events to late-joining subscribers
- Blended Declarative (React) + Imperative (direct DOM manipulation for precise cursor/highlight control)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser SPA
    subgraph "Browser SPA"
        direction TB

        subgraph "Networking Layer"
            direction TB
            TP["TutorProvider (Context + WS)"]:::frontend
            TC["TutorContext"]:::frontend
            WS["WebSocket Config"]:::frontend
            UWS["useWebSocket Hook"]:::hook
        end

        subgraph "Event Bus Layer"
            direction TB
            EB["Event Bus (mitt)"]:::internal
            RB["Ring Buffer"]:::internal
            URB["useRingBuffer Hook"]:::hook
            UEM["useEmitter Hook"]:::hook
            CRB["createRingBuffer"]:::util
        end

        subgraph "Presentation Layer"
            direction TB
            SP["SlidePanel"]:::frontend
            IS["InteractableSlide"]:::frontend
            QS["QuestionSlide"]:::frontend
            D1["GeometryArcDiagram"]:::frontend
            D2["GeometryArcDiagramHTML"]:::frontend
            UI["UI Components"]:::uiComp
        end

        subgraph "Interaction Layer"
            direction TB
            HI["useHighlighter"]:::hook
            PC["usePointerControl"]:::hook
            IA["useInteractables"]:::hook
            AP["useAudioPlayer"]:::hook
            SI["useSlideInteraction"]:::hook
            TE["useTutorEvents"]:::hook
            TR["useTranscript"]:::hook
            VR["useVoiceRecorder"]:::hook
        end

        subgraph "Utils & Assets"
            direction TB
            PBA["playBase64Audio"]:::util
            UT["utils.ts"]:::util
            PUB["public/"]:::asset
            AS["audioBase64.js"]:::asset
            CSS["Styles & CSS"]:::asset
        end
    end

    %% Mock Backend
    subgraph "Mock WS Server" 
        MS["mock-server/server.js"]:::backend
    end

    %% Connections
    SP -->|click START_SESSION| TP
    TP -->|WebSocket| MS
    MS -->|POINT/AUDIO/HIGHLIGHT Events| TP
    TP -->|emit JSON| EB
    EB -->|store| RB
    EB -->|notify| PC
    EB -->|notify| HI
    EB -->|notify| AP
    EB -->|notify| SI
    IS -->|on mount emit metadata| TP

    %% Click Events
    click TP "https://github.com/ayushmehre/padhai-assignment/blob/main/src/providers/TutorProvider.jsx"
    click TC "https://github.com/ayushmehre/padhai-assignment/blob/main/src/context/TutorContext.js"
    click WS "https://github.com/ayushmehre/padhai-assignment/blob/main/src/config/socket.js"
    click UWS "https://github.com/ayushmehre/padhai-assignment/blob/main/src/hooks/useWebSocket.js"
    click UEM "https://github.com/ayushmehre/padhai-assignment/blob/main/src/hooks/useEmitter.js"
    click URB "https://github.com/ayushmehre/padhai-assignment/blob/main/src/hooks/useRingBuffer.js"
    click CRB "https://github.com/ayushmehre/padhai-assignment/blob/main/src/lib/createRingBuffer.js"
    click SP "https://github.com/ayushmehre/padhai-assignment/blob/main/src/components/SlidePanel.jsx"
    click IS "https://github.com/ayushmehre/padhai-assignment/blob/main/src/components/InteractableSlide.jsx"
    click QS "https://github.com/ayushmehre/padhai-assignment/blob/main/src/slides/QuestionSlide.jsx"
    click D1 "https://github.com/ayushmehre/padhai-assignment/blob/main/src/components/diagrams/GeometryArcDiagram.jsx"
    click D2 "https://github.com/ayushmehre/padhai-assignment/blob/main/src/components/diagrams/GeometryArcDiagramHTML.jsx"
    click UI "https://github.com/ayushmehre/padhai-assignment/blob/main/src/components/ui/index.ts"
    click PBA "https://github.com/ayushmehre/padhai-assignment/blob/main/src/lib/playBase64Audio.js"
    click UT "https://github.com/ayushmehre/padhai-assignment/blob/main/src/lib/utils.ts"
    click PUB "https://github.com/ayushmehre/padhai-assignment/tree/main/public/"
    click AS "https://github.com/ayushmehre/padhai-assignment/blob/main/src/assets/audioBase64.js"
    click MS "https://github.com/ayushmehre/padhai-assignment/blob/main/mock-server/server.js"

    %% Styling
    classDef frontend fill:#E0F7FA,stroke:#006064,stroke-width:1px
    classDef backend fill:#FFE0B2,stroke:#E65100,stroke-width:1px
    classDef internal fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px
    classDef hook fill:#F1F8E9,stroke:#558B2F,stroke-width:1px
    classDef util fill:#FFF3E0,stroke:#EF6C00,stroke-width:1px
    classDef uiComp fill:#E3F2FD,stroke:#1565C0,stroke-width:1px
    classDef asset fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1px
```
