A suite of interactive classroom management tools with real-time student engagement features.
Classroom Widgets is a real-time classroom management system that enables teachers to create interactive activities and engage with students through various widget tools. The system consists of:
- Teacher Application: A React-based interface for creating and managing classroom activities
- Student Application: A responsive web app for students to participate in activities.
- Backend Server: An Express.js server handling real-time communication via Socket.io.
- Interactive: Poll, Questions, Drop Box, Handout, Real-time Feedback.
- Utility: Timer, Randomiser, List, Task Cue, Traffic Light.
- Display: Text Banner, Image Display, QR Code, Sound Effects, Stickers.
- Node.js 18+ and npm
- Git
- Docker and Docker Compose (for production deployment)
# Clone the repository
git clone https://github.com/yourusername/classroom-widgets.git
cd classroom-widgets
# Install all dependencies
npm run install:allTo run all services (recommended):
npm run devThis automatically starts:
- Teacher app: http://localhost:3000 (Vite dev server)
- Student app: http://localhost:3002/student (Vite dev server)
- Server: http://localhost:3001 (Express + Socket.io)
npm run build:allThe project is a monorepo consisting of three main parts that run concurrently during development using npm run dev.
┌─────────────────┐ ┌─────────────────┐
│ Teacher App │ │ Student App │
│ (Vite + React)│ │ (Vite + React) │
│ localhost:3000 │ │ localhost:3002 │
└────────┬────────┘ └────────┬────────┘
│ │
└─────────┬─────────────────┘
│
┌───────▼────────┐
│ Express Server │
│ (Socket.io) │
│ localhost:3001 │
└────────────────┘
Note: In development, each frontend runs on its own Vite dev server for hot module replacement (HMR). In production, both are served as static files by the Express server.
The repository is structured as a monorepo with three package.json files, orchestrating the three main parts of the application.
classroom-widgets/
├── src/ # Teacher App source code (Vite + React)
│ ├── components/ # Widget and UI components
│ ├── features/ # Feature-based modules (widgets, session, etc.)
│ ├── store/ # Zustand state management
│ └── index.tsx # Main entry point for the Teacher App
├── server/ # Backend and Student App workspace
│ ├── src/ # Server source code
│ │ ├── server.js # Main Express + Socket.io server entry point
│ │ ├── config/ # Environment and app configuration
│ │ ├── middleware/ # Express middleware
│ │ ├── routes/ # API routes
│ │ ├── sockets/ # Socket.IO event handlers
│ │ └── student/ # Student App source code (Vite + React)
│ │ ├── src/ # Student App components and logic
│ │ └── package.json # Student App dependencies
│ ├── public/ # Built Student App (served by Express)
│ └── package.json # Backend server dependencies
├── docs/ # Project documentation
├── package.json # Root package (for Teacher App) and monorepo scripts
└── vite.config.js # Vite config for the Teacher App
- Frontend: React 18, TypeScript, Tailwind CSS, Vite
- Backend: Express.js, Socket.io
- State Management: Zustand
- Deployment: Docker, Nginx
- Poll: Real-time voting with live results
- Questions: Q&A submission and management
- Drop Box: Collect links and text submissions from students
- Handout: Push content (links, text) to all students
- RT Feedback: Real-time understanding gauge (1-5 scale)
- Timer: Countdown and stopwatch functionality
- Randomiser: Random selection with visual effects
- List: Task management with completion tracking
- Task Cue: Visual work mode indicators
- Traffic Light: Status indicators
- Text Banner: Customizable text displays
- Image Display: Image viewer
- QR Code: Generate QR codes for sharing
- Sound Effects: Audio playback
- Sticker: Decorative elements
- Teacher creates session: Automatic 5-character code generation
- Students join: Enter code at
/studentURL - Real-time sync: All activities update instantly
- Multi-widget support: Multiple activities per session
- Drag & Drop: Position widgets anywhere on the workspace
- Resize: Adjust widget sizes with aspect ratio constraints
- Voice Commands: Hands-free widget control using speech recognition + AI
- Backgrounds: Multiple pattern options
- Dark Mode: System-aware theme switching
- Toolbar Customization: Choose which widgets to display
- Workspace Persistence: Auto-saves layout
Control widgets hands-free using natural language:
- Speech Recognition: Uses Annyang library for voice input
- Hybrid Processing: Fast pattern matching (~5ms) + AI fallback via Ollama (~200-800ms)
- Single Source of Truth: All commands defined in
shared/voiceCommandDefinitions.json - Auto-Sync: TypeScript/JavaScript generated automatically to keep frontend/backend in sync
Example commands: "start a 5 minute timer", "launch the poll widget", "pick someone at random"
See VOICE_COMMAND_SHARED_DEFINITIONS.md for details.
The most important scripts are run from the root package.json:
# Install all dependencies in all workspaces
npm run install:all
# Run Teacher App, Student App, and Server concurrently
npm run dev
# Build all applications for production (auto-generates voice types)
npm run build:all
# Regenerate voice command type definitions (TypeScript/JavaScript)
npm run generate:voice-types
# Start the production server
npm start
# Run tests for the Teacher App
npm testSee Getting Started Guide for more development details.
If you're using Claude Code to assist with development, ask it to check for a running tmux session. Claude Code can read the dev server logs directly from tmux using:
# List tmux sessions
tmux list-sessions
# Capture recent logs (last 100 lines)
tmux capture-pane -t 0 -p -S -100Recommended setup:
- Start a tmux session:
tmux new -s dev - Run the dev servers:
npm run dev(ornpm run dev:concurrent) - Claude Code can then monitor logs alongside you
# Copy the example file to get started
cp .env.example .env
# Edit .env to add your API keys (optional)
nano .envSee Environment Setup Guide for complete environment configuration guide.
See Adding New Widget Guide for a step-by-step guide.
Use npm version to bump the version, commit, and tag in one step — the version is displayed in the app UI and is read from the root package.json:
npm version 1.2.3
git push origin master --tagsPushing a v* tag triggers the GitHub Actions workflow which auto-deploys to production.
Note: This workflow is untested end-to-end. Verify that
npm versioncorrectly creates the git tag and that the version displayed in the app reflects the rootpackage.jsonbefore relying on it.
See Deployment Guide for full instructions including CD setup, Docker, and environment configuration.
All comprehensive documentation is in the docs/ directory:
- Getting Started - Quick developer onboarding
- Architecture - In-depth technical documentation
- Adding New Widget - Widget creation guide
- Socket Events - Real-time communication protocol
- Voice Command Shared Definitions - Voice command synchronization system
- Deployment Guide - Production deployment (Docker, SSL, troubleshooting)
- Analytics Setup - Privacy-focused analytics with Umami
- Main Documentation - Comprehensive project reference
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit changes:
git commit -m 'Add amazing feature' - Push to branch:
git push origin feature/amazing-feature - Open a Pull Request
This project is licensed under the MIT License.