# 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`*