Initial commit: Sarthi Lab desktop application

2026-03-11 03:59:38 +05:30
commit bb1ec0a584
49 changed files with 15191 additions and 0 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,120 @@
+# AGENTS.md
+
+> **Quick Reference Card** for Sarthi Lab development
+
+---
+
+## What Is This?
+
+**Sarthi Lab** - Desktop application for computer labs in schools. Students use this offline-capable Electron app to access interactive science experiments and exercises.
+
+Built with **Electron + React + Vite**.
+
+---
+
+## Project Structure
+
+```
+/sarthi_lab/
+├── src/
+│   ├── components/       # React components
+│   ├── screens/           # Screen components (Login, Dashboard, Exercise, etc.)
+│   ├── hooks/             # Custom React hooks
+│   ├── services/          # API services (labApi.js)
+│   ├── store/             # Zustand state management
+│   └── App.jsx            # Main app component
+├── electron/
+│   └── main.js            # Electron main process
+├── dist/                  # Production build
+├── dist-electron/         # Electron production build
+└── package.json
+```
+
+---
+
+## Tech Stack
+
+| Component | Technology |
+|-----------|------------|
+| **Framework** | Electron 33+ |
+| **Frontend** | React 19, Vite 6 |
+| **Styling** | Tailwind CSS |
+| **State** | Zustand |
+| **Build** | electron-builder |
+
+---
+
+## Development
+
+```bash
+cd sarthi_lab
+
+# Install dependencies
+npm install
+
+# Start development (runs both Vite + Electron)
+npm run dev
+```
+
+App runs at `http://localhost:5174` in development.
+
+---
+
+## Key Features
+
+1. **Server Connection** - Connect to backend via URL + room token
+2. **Student Authentication** - Students log in with room token + credentials
+3. **Exercise Library** - Browse and launch interactive science experiments
+4. **Voice Integration** - TTS/STT via desktop backend
+5. **Heartbeat** - Periodic ping to server to track active students
+
+---
+
+## API Integration
+
+Sarthi Lab connects to the Django backend (`/server`):
+
+| Endpoint | Purpose |
+|----------|---------|
+| `/api/dashboard/student/room/join/` | Join a room with token |
+| `/api/dashboard/student/dashboard/` | Get student profile & courses |
+| `/api/exercises` | List available exercises |
+| `/api/exercises/{id}/access-url` | Get secure exercise URL with token |
+| `/api/dashboard/student/heartbeat/` | Send periodic heartbeat |
+
+---
+
+## Exercise Loading Flow
+
+1. Student clicks exercise → calls `/api/exercises/{id}/access-url`
+2. Backend returns URL with token: `/api/exercises/{id}/latest/index.html?t=<token>`
+3. App loads URL in iframe
+4. Backend validates token before serving content
+
+---
+
+## Build Commands
+
+```bash
+# Development
+npm run dev
+
+# Build for production (creates .app for macOS)
+npm run build
+
+# Preview production build
+npm run preview
+```
+
+---
+
+## Known Issues / Notes
+
+- Exercise iframes require valid access token - check `ExerciseScreen.jsx`
+- CSP on server must allow `localhost:5174` and `sarthi.eduspheria.com`
+- Uses Electron IPC for desktop features (TTS, file system)
+- Stores config in Electron store (server URL, room token)
+
+---
+
+*For root AGENTS.md with company context, see `/AGENTS.md`*