How ayushmehre/padhai-assignment works
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)