docs: Update README.md with Physics simulations, CAD importer, WebSockets classroom, and Render deployment

Author: ShyamAlancode

README.md

@@ -1,109 +1,120 @@
-# Mindscape
+# Mindscape AI — AI Spatial Reasoning & STEM 3D Tutor
 
-Mindscape turns a static maths or physics worksheet into an interactive 3D lesson. Learners upload a diagram or type a question, inspect and manipulate the generated scene, then explain their reasoning to receive focused feedback rather than just an answer.
+Mindscape turns static STEM worksheets, 3D CAD models, and physics problems into an interactive, real-time 3D playground. Learners upload diagrams or CAD files, explore electric field vector mechanics, manipulate generated scenes, and participate in multi-user real-time 3D classrooms with live AI spatial tutoring.
 
-The flagship flow is a surface-area lesson: worksheet to labelled 3D solid, then exploration, prediction, explanation, and a follow-up challenge.
+---
 
-## Try the judge-safe demo
+## Key Capabilities
 
-Start the app and open [http://localhost:3000/?demo=true](http://localhost:3000/?demo=true). The guided cuboid surface-area lesson runs through the local planner and does not require API keys. It is designed for a reliable demo recording or judge review.
+### ⚡ 1. Advanced Interactive Physics & Vector Simulations
+- **Coulomb Force Vector Arrows**: Real-time 3D visualization of pairwise electrostatic forces ($F_{ij} = k \frac{q_i q_j}{r_{ij}^2} \hat{r}_{ij}$) with attraction/repulsion color dynamics and magnitude vectors.
+- **Dynamic Field Line Particle Flow**: Interactive RK4 streamline particle flow visualizing electric field lines.
+- **Physics Playground Simulation**: Play/Pause trajectory integration accelerating charges under electrostatic forces.
 
-## Local setup
+### 📦 2. Custom 3D Model & CAD Importer (.gltf / .glb / .obj / .stl)
+- **Drag & Drop Viewport Uploading**: Learners and engineers can drag custom 3D files directly into the Three.js viewport.
+- **AI Spatial Analysis Metrics**: Automated geometry extraction (bounding box dimensions $dx, dy, dz$, surface area, estimated volume, vertex & face counts) fed directly to the AI Tutor for spatial reasoning.
 
-### Requirements
+### 👥 3. Multi-User Real-Time 3D Classroom (WebSockets)
+- **Shared 3D Canvas Rooms**: Join via 6-character room code to connect teachers and learners live.
+- **Real-Time Spatial Sync**: Object creation, scaling, rotation, deletion, presence cursor indicators, and tutor hints sync instantly across devices via WebSockets (`wss://`).
+
+---
 
-- Node.js 20+
-- npm
-- Webcam for hand tracking
-- Microphone for push-to-talk voice mode
+## Quick Start & Local Setup
+
+### Requirements
+- **Node.js 22+**
+- **npm**
+- Webcam (optional, for hand tracking)
+- Microphone (optional, for push-to-talk voice mode)
 
-### Install
+### Installation
 
 ```bash
+# Install dependencies
 npm install
 pip install -r requirements.txt
 ```
 
-### Environment
+### Environment Configuration
 
-Create `.env.local` in the project root:
+Create a `.env.local` file in the project root:
 
 ```env
 GEMINI_API_KEY=your_google_ai_studio_key
 GROQ_API_KEY=your_groq_api_key
 ```
 
-The app requires these keys for vision (Gemini), conversational tutoring (Groq), and transcription (Groq).
-
-## Run
+### Development Server
 
 ```bash
 npm run dev
 ```
 
-Then open `http://localhost:3000`. Use `?demo=true` for the no-key guided worksheet demo.
+Open [http://localhost:3000](http://localhost:3000) in your browser. Use `?demo=true` for the offline guided worksheet demo.
 
-## Verify
+### Quality & Test Suite
 
 ```bash
 npm run quality
 ```
 
-This runs linting and the complete automated test suite.
-
-## Built with Codex and GPT-5.6
-
-Codex and GPT-5.6 were used to stabilize the interactive lesson flow, repair the streaming voice lifecycle, add a no-key demo path, strengthen test coverage, and refine the submission-ready product experience. The project keeps deterministic lesson and scene fallbacks so the core learning journey remains demonstrable when external model services are unavailable.
-
-## Architecture
- 
- ### High-level system design
- 
- ```text
- +---------------------------------------------------------------+
- | Frontend                                                      |
- | Vanilla JS + Three.js                                         |
- |                                                               |
- | - Question input (text, image, screenshot)                    |
- | - 3D scene rendering                                          |
- | - Tutor panel                                                 |
- | - Voice UI (Browser Web Speech API)                           |
- | - Hand tracking                                               |
- | - KaTeX rendering                                             |
- | - Real-time "Limited Mode" alerts                             |
- +---------------------------------------------------------------+
+Runs ESLint and the complete automated unit test suite (170+ tests).
+
+---
+
+## ☁️ Free Cloud Deployment (Render)
+
+Mindscape AI includes a production multi-stage `Dockerfile` (Node 22) and `render.yaml` blueprint for 1-click free deployment on **Render** with full WebSocket (`wss://`) support.
+
+### 1-Click Render Deployment
+1. Push code to your GitHub repository.
+2. Log into [Render Dashboard](https://dashboard.render.com/) $\rightarrow$ Click **New +** $\rightarrow$ **Blueprint**.
+3. Select your repository. Render will automatically detect `render.yaml`, build Vite production assets, and launch the Node.js + WebSocket Web Service for free.
+
+---
+
+## System Architecture
+
+```text
++---------------------------------------------------------------+
+| Frontend                                                      |
+| Vanilla JS + Three.js + WebSockets                            |
+|                                                               |
+| - Question & CAD Input (text, image, .gltf, .obj, .stl)       |
+| - Physics Simulation & Coulomb Vector Arrow Overlay           |
+| - Multi-User Real-Time 3D Classroom UI                        |
+| - AI Tutor & KaTeX math rendering                             |
+| - Hand tracking & 3D gesture controls                         |
++---------------------------------------------------------------+
                             |
-                            | HTTP / SSE
+                            | HTTP / SSE / WebSockets (ws://)
                             v
- +---------------------------------------------------------------+
- | Backend                                                       |
- | Node.js + Hono API                                            |
- |                                                               |
- | - Request validation                                          |
- | - Gemini & Groq Hybrid integration                            |
- | - 3-Tier Model Failover (Gemini -> Groq 70B -> Groq 8B)       |
- | - Text-as-Vision Fallback (Rescues scene interpretation)      |
- | - SceneSpec generation (Strict JSON enforcement)              |
- | - Tutor streaming                                             |
- | - Voice pipeline coordination (Whisper STT)                   |
- +---------------------------------------------------------------+
++---------------------------------------------------------------+
+| Backend Server                                                |
+| Node.js 22 + Hono API + WebSocket Room Manager                |
+|                                                               |
+| - Real-time Classroom Room Broadcasting                       |
+| - Gemini & Groq Hybrid AI Orchestration                       |
+| - 3D CAD Geometric Metrics Extraction                         |
+| - 3-Tier Model Failover (Gemini -> Groq 70B -> Groq 8B)       |
+| - SceneSpec generation & Tutor Streaming                      |
++---------------------------------------------------------------+
                             |
              +--------------+--------------+
              v                             v
- +-----------------------+     +-----------------------+
- | Google Gemini         |     | Groq (Llama 3)        |
- |                       |     |                       |
- | - Primary Vision      |     | - Primary Reasoning   |
- | - Primary Planning    |     | - Whisper STT (v3)    |
- | - Failover Chat       |     | - 70B Scene Planning  |
- |                       |     | - Visual Failover     |
- +-----------------------+     +-----------------------+
- ```
-
-## Hardened Failover System
-
-The system is built for hackathon-grade resiliency:
-- **Vision Fallback**: If Gemini 2.0 Flash hits quota or fails, the system automatically falls back to **Llama 3.2 11B Vision** on Groq.
-- **Interpretation Fallback**: If all vision models fail to interpret a diagram, the system uses the high-capacity **Llama 3.3 70B** to interpret the question text alone, ensuring a valid 3D scene is still built.
-- **Search Fallback**: Semantic search (Gemini Embeddings) automatically falls back to **Lexical Keyword Search** if the API key is restricted or out of quota.
-- **Transparency**: The UI displays a "Limited Mode" warning in the evidence panel whenever the system is operating in a fallback state.
++-----------------------+     +-----------------------+
+| Google Gemini         |     | Groq (Llama 3)        |
+|                       |     |                       |
+| - Primary Vision      |     | - Primary Reasoning   |
+| - Primary Planning    |     | - Whisper STT         |
+| - Failover Chat       |     | - 70B Scene Planning  |
++-----------------------+     +-----------------------+
+```
+
+---
+
+## License & Credits
+
+Built with Three.js, Hono, Node.js 22, Google Gemini API, and Groq SDK.