docs: rewrite README with full project docs, architecture, team & contributors

- Full architecture diagram (3-pipeline ensemble)
- Complete project structure, tech stack, setup guide
- Deployment instructions for HF Spaces + Vercel
- Team section: Devrajsinh Gohil, Jay Nasit, Dr. Om Prakash Suthar

fix: calibration overlay is now transparent so camera feed stays visible
- UI moved to compact bottom card so user can see their hand during calibration

README.md

@@ -1,154 +1,268 @@
+<div align="center">
 
-# SanketSetu
+# 🤟 SanketSetu | સંકેત-સેતુ
 
-A real-time sign language recognition system using machine learning and computer vision.
+**Real-time Gujarati Sign Language Recognition System**
 
-## Project Structure
+[![Live Demo](https://img.shields.io/badge/Live%20Demo-Vercel-black?style=for-the-badge&logo=vercel)](https://sanket-setu.vercel.app)
+[![Backend](https://img.shields.io/badge/Backend-HuggingFace%20Spaces-yellow?style=for-the-badge&logo=huggingface)](https://huggingface.co/spaces/devrajsinh2012/Sanket-Setu)
+[![License](https://img.shields.io/badge/License-All%20Rights%20Reserved-red?style=for-the-badge)](#license)
+
+</div>
+
+---
+
+## 📖 About
+
+**SanketSetu** (Sanskrit: *Sanket* = gesture/sign, *Setu* = bridge) is a production-grade, real-time **Gujarati Sign Language (GSL)** recognition system. It bridges the communication gap between the hearing-impaired community and the broader public by translating hand gestures corresponding to **34 Gujarati consonants** (ક–જ્ઞ) into text — all in real time, directly in the browser.
+
+The system uses your device camera, processes hand landmarks locally via **MediaPipe**, and sends them over a **WebSocket** connection to a machine-learning backend that classifies the gesture using a **3-pipeline ensemble** of models.
+
+---
+
+## ✨ Features
+
+- **Real-time gesture detection** — sub-100 ms end-to-end latency
+- **3-pipeline ensemble inference** — XGBoost → Autoencoder+LightGBM → CNN+SVM, invoked in order of confidence
+- **34 Gujarati sign classes** — complete consonant alphabet (ક, ખ, ગ … ક્ષ, જ્ઞ)
+- **WebSocket streaming** — live bidirectional communication between browser and backend
+- **MediaPipe hand tracking** — 21 landmark coordinates extracted client-side (no raw video sent to server)
+- **Onboarding wizard** — animated step-by-step guide for first-time users
+- **Calibration screen** — transparent overlay keeps camera feed fully visible while detecting hand readiness
+- **Landmark canvas overlay** — live 21-point skeleton drawn over the webcam feed
+- **Prediction HUD** — displays recognised sign, confidence bar, latency, and prediction history
+- **Low-bandwidth mode** — auto-throttles to 5 fps when latency is high
+- **Docker-ready backend** — deployable on Hugging Face Spaces in one push
+
+---
+
+## 🏗️ System Architecture
 
 ```
-Γö£ΓöÇΓöÇ backend/              # FastAPI backend server
-Γöé   Γö£ΓöÇΓöÇ app/             # Main application code
-Γöé   Γöé   Γö£ΓöÇΓöÇ inference/   # ML inference pipelines
-Γöé   Γöé   ΓööΓöÇΓöÇ models/      # Model loading and management
-Γöé   ΓööΓöÇΓöÇ tests/           # Backend tests
-Γö£ΓöÇΓöÇ frontend/            # React + TypeScript frontend
-Γöé   ΓööΓöÇΓöÇ src/
-Γöé       Γö£ΓöÇΓöÇ components/  # React components
-Γöé       Γö£ΓöÇΓöÇ hooks/       # Custom React hooks
-Γöé       ΓööΓöÇΓöÇ lib/         # Utility libraries
-Γö£ΓöÇΓöÇ CNN_Autoencoder_LightGBM/  # CNN Autoencoder + LightGBM model
-Γö£ΓöÇΓöÇ CNN_PreTrained/              # CNN + SVM model
-ΓööΓöÇΓöÇ Mediapipe_XGBoost/          # MediaPipe + XGBoost model
+Browser (React + TypeScript)
+│
+├─ MediaPipe Hands (WASM)    ← extracts 21 hand landmarks (63 floats) locally
+├─ WebcamFeed + LandmarkCanvas
+├─ Calibration / Onboarding UI
+│
+└─ WebSocket (wss://)
+        │
+        ▼
+FastAPI Backend (Python)
+│
+├─ Pipeline A — XGBoost (63 landmarks → 34 classes)        ← primary, fastest
+│       └─ if confidence < 0.70 ↓
+├─ Pipeline B — Autoencoder (63→16) + LightGBM             ← secondary
+│       └─ if confidence < 0.60 ↓
+└─ Pipeline C — ResNet50 CNN (128×128 image) + SVM         ← tertiary
+        └─ Ensemble weighted average → final prediction
 ```
 
-## Features
+---
 
-- Real-time sign language gesture recognition
-- Multiple ML model ensemble approach
-- WebSocket-based real-time communication
-- MediaPipe hand landmark tracking
-- Interactive webcam feed with visual feedback
-- Prediction confidence display
+## 📁 Project Structure
+
+```
+SanketSetu/
+├── backend/
+│   ├── app/
+│   │   ├── main.py              # FastAPI entry-point, WebSocket + REST
+│   │   ├── config.py            # Settings (thresholds, model paths, env vars)
+│   │   ├── schemas.py           # Pydantic request/response models
+│   │   ├── inference/
+│   │   │   ├── pipeline_a.py    # XGBoost inference (63 MediaPipe landmarks)
+│   │   │   ├── pipeline_b.py    # Autoencoder encoder + LightGBM
+│   │   │   ├── pipeline_c.py    # ResNet CNN + SVM (image-based)
+│   │   │   └── ensemble.py      # Confidence-weighted ensemble logic
+│   │   └── models/
+│   │       ├── loader.py        # Singleton model loader
+│   │       └── label_map.py     # Index 0–33 → Gujarati character
+│   ├── tests/                   # Pytest test suite
+│   ├── requirements.txt
+│   └── requirements-dev.txt
+│
+├── frontend/
+│   ├── src/
+│   │   ├── App.tsx              # App shell, stage machine (onboarding → calibration → running)
+│   │   ├── components/
+│   │   │   ├── WebcamFeed.tsx       # Webcam stream + canvas overlay
+│   │   │   ├── LandmarkCanvas.tsx   # Draws 21-point hand skeleton
+│   │   │   ├── PredictionHUD.tsx    # Live sign, confidence bar, latency, history
+│   │   │   ├── OnboardingGuide.tsx  # Animated intro wizard
+│   │   │   └── Calibration.tsx      # Transparent hand-detection calibration card
+│   │   ├── hooks/
+│   │   │   ├── useWebSocket.ts      # WS connection, send/receive
+│   │   │   ├── useMediaPipe.ts      # MediaPipe Hands JS integration
+│   │   │   └── useWebcam.ts         # Camera permissions + stream
+│   │   └── lib/
+│   │       └── landmarkUtils.ts     # Landmark normalisation helpers
+│   ├── .env.production          # VITE_WS_URL for Vercel build
+│   ├── vite.config.ts
+│   └── package.json
+│
+├── CNN_Autoencoder_LightGBM/    # Autoencoder + LightGBM model weights
+├── CNN_PreTrained/              # ResNet CNN + SVM model weights
+├── Mediapipe_XGBoost/           # XGBoost model weights
+├── Dockerfile                   # Multi-stage Docker build for HF Spaces
+└── start.ps1                    # One-command local dev launcher (Windows)
+```
 
-## Tech Stack
+---
 
-### Backend
-- FastAPI
-- Python 3.x
-- PyTorch
-- LightGBM
-- XGBoost
-- MediaPipe
+## 🛠️ Tech Stack
 
-### Frontend
-- React
-- TypeScript
-- Vite
-- TailwindCSS
+| Layer | Technology |
+|---|---|
+| **Frontend** | React 18, TypeScript, Vite, TailwindCSS, Framer Motion |
+| **Hand Tracking** | MediaPipe Hands (browser WASM) |
+| **Real-time Comm.** | WebSocket (native browser API) |
+| **Backend** | FastAPI, Python 3.10+ |
+| **ML — Pipeline A** | XGBoost (scikit-learn API) |
+| **ML — Pipeline B** | Keras/TensorFlow Autoencoder + LightGBM |
+| **ML — Pipeline C** | PyTorch ResNet50 CNN + scikit-learn SVM |
+| **Deployment** | Hugging Face Spaces (Docker SDK) + Vercel |
 
-## Getting Started
+---
+
+## 🚀 Getting Started
 
 ### Prerequisites
-- Python 3.8+
-- Node.js 16+
+
+- Python 3.10+
+- Node.js 18+
 - npm or yarn
 
-### Backend Setup
+### 1. Clone the repository
+
+```bash
+git clone https://github.com/devrajsinh2012/Sanket-Setu.git
+cd Sanket-Setu
+```
+
+### 2. Backend Setup
 
 ```bash
 cd backend
 pip install -r requirements.txt
+# Starts FastAPI server on http://localhost:8000
 python -m app.main
 ```
 
-### Frontend Setup
+### 3. Frontend Setup
 
 ```bash
 cd frontend
 npm install
+# Starts Vite dev server on http://localhost:5173
 npm run dev
 ```
 
-## Development
+### 4. One-Command Start (Windows)
 
-Run the development servers:
-
-```bash
-# Start both frontend and backend
+```powershell
+# From the repo root — starts both backend and frontend
 .\start.ps1
 ```
 
-## Deployment
+---
+
+## 🧪 Testing
 
-### Backend ΓÇö Hugging Face Spaces (Docker SDK)
+```bash
+cd backend
+pytest tests/ -v
+```
 
-The backend is deployed as a [Hugging Face Space](https://huggingface.co/spaces) using the Docker SDK.
+---
 
-**Steps to create a new Space and push:**
+## 🐳 Docker (Local)
 
-1. **Create the Space** on [huggingface.co/new-space](https://huggingface.co/new-space)
-   - SDK: **Docker**
-   - Visibility: Public (or Private)
-   - Note your `username` and `space-name`
+```bash
+# Build the image
+docker build -t sanketsetu .
 
-2. **Clone the Space repo and push your code:**
-   ```bash
-   # Add HF Space as a remote (from repo root)
-   git remote add space https://huggingface.co/spaces/devrajsinh2012/Sanket-Setu
+# Run on port 7860 (matches HF Spaces)
+docker run -p 7860:7860 sanketsetu
+```
 
-   git push space main
-   ```
-   HF Spaces will automatically build the Docker image and start the container.
+---
 
-3. **Set Space Secrets** (via HF Space → Settings → Repository secrets):
-   | Secret | Example value |
-   |--------|---------------|
-   | `CORS_ORIGINS` | `https://sanketsetu.vercel.app,http://localhost:5173` |
-   | `PIPELINE_MODE` | `ensemble` |
-   | `CONFIDENCE_THRESHOLD` | `0.70` |
+## ☁️ Deployment
 
-4. **Update the frontend** ΓÇö set the `VITE_WS_URL` Vercel environment variable:
-   ```
-   wss://devrajsinh2012-sanket-setu.hf.space
-   ```
-   In Vercel dashboard: **Settings → Environment Variables → VITE_WS_URL**
+### Backend — Hugging Face Spaces
 
-**Space URL format:**
-- HTTPS API: `https://devrajsinh2012-sanket-setu.hf.space`
-- WebSocket:  `wss://devrajsinh2012-sanket-setu.hf.space/ws/landmarks`
-- Health:     `https://devrajsinh2012-sanket-setu.hf.space/health`
+The backend runs as a [Hugging Face Space](https://huggingface.co/spaces/devrajsinh2012/Sanket-Setu) using the **Docker SDK**.
 
-### Frontend ΓÇö Vercel
+**Push to the Space:**
 
 ```bash
-cd frontend
-# deploy via Vercel CLI or connect the GitHub repo in Vercel dashboard
+# From repo root
+git push space main
 ```
 
-Set the `VITE_WS_URL` environment variable in Vercel to the HF Space WebSocket URL above.
+HF Spaces automatically builds the Docker image and serves the container on port 7860.
 
-## Docker (local)
+**Space Secrets** (HF Space → Settings → Repository secrets):
 
-Build and run using Docker locally:
+| Secret | Example value |
+|--------|---------------|
+| `CORS_ORIGINS` | `https://sanket-setu.vercel.app,http://localhost:5173` |
+| `PIPELINE_MODE` | `ensemble` |
+| `CONFIDENCE_THRESHOLD` | `0.70` |
 
-```bash
-docker build -t sanketsetu .
-docker run -p 7860:7860 sanketsetu
-```
+**Live URLs:**
 
-## Testing
+| Endpoint | URL |
+|---|---|
+| Health check | `https://devrajsinh2012-sanket-setu.hf.space/health` |
+| WebSocket | `wss://devrajsinh2012-sanket-setu.hf.space/ws/landmarks` |
 
-Run backend tests:
+### Frontend — Vercel
 
-```bash
-cd backend
-pytest
-```
+Connect the GitHub repository in the [Vercel dashboard](https://vercel.com) and add the **Environment Variable**:
+
+| Variable | Value |
+|---|---|
+| `VITE_WS_URL` | `wss://devrajsinh2012-sanket-setu.hf.space` |
+
+Vercel auto-deploys on every push to `main`.
+
+---
+
+## 🔧 Environment Variables
+
+| Variable | Scope | Default | Description |
+|---|---|---|---|
+| `VITE_WS_URL` | Frontend (build-time) | — | WebSocket URL of the backend |
+| `CORS_ORIGINS` | Backend (runtime) | `*` | Comma-separated allowed origins |
+| `PIPELINE_MODE` | Backend (runtime) | `ensemble` | `ensemble` / `A` / `B` / `C` |
+| `CONFIDENCE_THRESHOLD` | Backend (runtime) | `0.70` | Primary confidence cutoff |
+| `SECONDARY_THRESHOLD` | Backend (runtime) | `0.60` | Secondary confidence cutoff |
+| `WEIGHTS_DIR` | Backend (runtime) | repo root | Override path to model weight files |
+
+---
+
+## 🤝 Contributing
+
+Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Please make sure to update tests as appropriate.
+
+---
+
+## 👥 Team & Acknowledgements
+
+This project was developed by:
+
+| Name | Contribution |
+|---|---|
+| **Devrajsinh Gohil** | Full-stack development, ML integration, deployment |
+| **Jay Nasit** | Machine learning models, dataset preparation, testing |
+
+**Guided by:** Dr. Om Prakash Suthar
 
-## License
+> We express our sincere gratitude to **Dr. Om Prakash Suthar** for his invaluable guidance, encouragement, and technical insights throughout the development of SanketSetu. His mentorship was instrumental in shaping both the research direction and the system architecture of this project.
 
-All rights reserved.
+---
 
-## Author
+## 📄 License
 
-Devrajsinh Gohil (devrajsinh2012)
+© 2026 Devrajsinh Gohil & Jay Nasit. All Rights Reserved.

frontend/src/components/Calibration.tsx

@@ -39,67 +39,79 @@ export function Calibration({ handDetected, onReady }: Props) {
   const isChecked = done;
 
   return (
-    <div
-      className="fixed inset-0 z-40 flex flex-col items-center justify-center gap-8"
-      style={{ background: 'rgba(5,8,22,0.92)', backdropFilter: 'blur(12px)' }}
-    >
-      <motion.h1
-        initial={{ opacity: 0, y: -20 }}
+    /* Transparent outer overlay — camera feed stays fully visible behind */
+    <div className="fixed inset-0 z-40 flex flex-col items-center justify-end pb-10 pointer-events-none">
+
+      {/* Compact card anchored at the bottom so the camera is unobstructed */}
+      <motion.div
+        initial={{ opacity: 0, y: 30 }}
         animate={{ opacity: 1, y: 0 }}
-        className="text-3xl font-bold glow-text"
+        className="pointer-events-auto flex flex-col items-center gap-5 px-8 py-6 rounded-2xl"
+        style={{
+          background: 'rgba(5,8,22,0.88)',
+          backdropFilter: 'blur(14px)',
+          border: '1px solid rgba(255,255,255,0.08)',
+          boxShadow: '0 8px 32px rgba(0,0,0,0.5)',
+        }}
       >
-        Ready?
-      </motion.h1>
+        <motion.h2
+          initial={{ opacity: 0, y: -10 }}
+          animate={{ opacity: 1, y: 0 }}
+          className="text-2xl font-bold glow-text"
+        >
+          Ready?
+        </motion.h2>
 
-      <motion.p
-        initial={{ opacity: 0 }}
-        animate={{ opacity: 1 }}
-        transition={{ delay: 0.2 }}
-        className="text-slate-400 text-center max-w-xs"
-      >
-        {handDetected
-          ? 'Hand detected — hold steady…'
-          : 'Please show your hand to the camera.'}
-      </motion.p>
+        <motion.p
+          initial={{ opacity: 0 }}
+          animate={{ opacity: 1 }}
+          transition={{ delay: 0.2 }}
+          className="text-slate-400 text-center text-sm max-w-xs"
+        >
+          {handDetected
+            ? 'Hand detected — hold steady…'
+            : 'Show your hand to the camera above.'}
+        </motion.p>
 
-      {/* Circular progress / check */}
-      <div className="relative w-24 h-24 flex items-center justify-center">
-        <svg className="absolute inset-0 w-full h-full -rotate-90" viewBox="0 0 96 96">
-          <circle cx="48" cy="48" r="40" fill="none" stroke="rgba(255,255,255,0.06)" strokeWidth="6" />
-          <motion.circle
-            cx="48" cy="48" r="40"
-            fill="none"
-            stroke="#00f5d4"
-            strokeWidth="6"
-            strokeLinecap="round"
-            strokeDasharray={`${2 * Math.PI * 40}`}
-            animate={{ strokeDashoffset: 2 * Math.PI * 40 * (1 - progress / 100) }}
-            transition={{ duration: 0.1 }}
-            style={{ filter: 'drop-shadow(0 0 6px #00f5d4)' }}
-          />
-        </svg>
+        {/* Circular progress / check */}
+        <div className="relative w-20 h-20 flex items-center justify-center">
+          <svg className="absolute inset-0 w-full h-full -rotate-90" viewBox="0 0 96 96">
+            <circle cx="48" cy="48" r="40" fill="none" stroke="rgba(255,255,255,0.06)" strokeWidth="6" />
+            <motion.circle
+              cx="48" cy="48" r="40"
+              fill="none"
+              stroke="#00f5d4"
+              strokeWidth="6"
+              strokeLinecap="round"
+              strokeDasharray={`${2 * Math.PI * 40}`}
+              animate={{ strokeDashoffset: 2 * Math.PI * 40 * (1 - progress / 100) }}
+              transition={{ duration: 0.1 }}
+              style={{ filter: 'drop-shadow(0 0 6px #00f5d4)' }}
+            />
+          </svg>
 
-        <AnimatePresence mode="wait">
-          {isChecked ? (
-            <motion.div
-              key="check"
-              initial={{ scale: 0, opacity: 0 }}
-              animate={{ scale: 1, opacity: 1 }}
-              transition={{ type: 'spring', stiffness: 400, damping: 20 }}
-            >
-              <CheckCircle size={40} style={{ color: '#00f5d4' }} />
-            </motion.div>
-          ) : (
-            <motion.div key="spinner" animate={{ rotate: 360 }} transition={{ duration: 1.5, repeat: Infinity, ease: 'linear' }}>
-              <Loader2 size={32} strokeWidth={1.5} style={{ color: handDetected ? '#00f5d4' : '#4b5563' }} />
-            </motion.div>
-          )}
-        </AnimatePresence>
-      </div>
+          <AnimatePresence mode="wait">
+            {isChecked ? (
+              <motion.div
+                key="check"
+                initial={{ scale: 0, opacity: 0 }}
+                animate={{ scale: 1, opacity: 1 }}
+                transition={{ type: 'spring', stiffness: 400, damping: 20 }}
+              >
+                <CheckCircle size={36} style={{ color: '#00f5d4' }} />
+              </motion.div>
+            ) : (
+              <motion.div key="spinner" animate={{ rotate: 360 }} transition={{ duration: 1.5, repeat: Infinity, ease: 'linear' }}>
+                <Loader2 size={28} strokeWidth={1.5} style={{ color: handDetected ? '#00f5d4' : '#4b5563' }} />
+              </motion.div>
+            )}
+          </AnimatePresence>
+        </div>
 
-      <p className="text-xs text-slate-600">
-        {isChecked ? 'All set!' : 'Keep your hand visible for 1 second'}
-      </p>
+        <p className="text-xs text-slate-500">
+          {isChecked ? 'All set!' : 'Keep your hand visible for 1 second'}
+        </p>
+      </motion.div>
     </div>
   );
 }