Swaya is an open-source, multi-tenant platform for running live quizzes, polls, word clouds, and proctored exams. Audiences join instantly via QR code or join code — no app, no login required.
Live demo: www.swaya.me
| Swaya | Kahoot | Mentimeter | Google Forms | |
|---|---|---|---|---|
| Self-hosted | Yes | No | No | No |
| Proctored exams | Yes | No | No | No |
| OTP email verification | Yes | No | No | No |
| AI question generation | Yes | No | No | No |
| Word cloud responses | Yes | No | Yes | No |
| 11 UI languages | Yes | Partial | Partial | No |
| Multi-tenant (SaaS-ready) | Yes | No | No | No |
| Export to PPTX / PDF / Excel | Yes | Limited | Limited | No |
| Open source | Yes | No | No | No |
- Live Quiz — Real-time competitive quizzes with instant leaderboards
- Live Poll — Gather audience feedback with live result visualization
- Word Cloud — Crowd-sourced responses rendered as a live word cloud with automatic profanity filtering
- Offline Poll — QR-code-based polling for physical spaces without an active host
- Exam Mode — Self-paced, timed exams with webcam proctoring, OTP email verification, and PDF reports
- AI Question Generation — Generate localized MCQ quizzes from a single prompt (Gemini 2.0 Flash)
- AI Result Analysis — Post-exam AI summary of class performance
- 11 languages — UI in English, Hindi, Tamil, Telugu, Kannada, Bengali, Gujarati, Spanish, French, German, Russian
- Multi-tenant — Each organization gets isolated data, branding, and tier-based limits
- Export — Results to PDF, Excel, and PowerPoint
Browser Clients (Host + Audience)
│ HTTPS
┌─────▼──────┐
│ Nginx │── / → frontend/dist (React SPA)
│ │── /api/* → FastAPI :8000
└─────┬──────┘
│
┌─────▼──────────────────────────────────┐
│ FastAPI (Python 3.10) │
│ 20 API routers · async service layer │
│ JWT auth · SSE real-time · Tier limits│
└──────┬──────────────────┬──────────────┘
│ │
┌──────▼──────┐ ┌───────▼───────┐
│ MySQL 8 │ │ Redis 7 │
│ (all data, │ │ (pub-sub, JWT │
│ tenant- │ │ blocklist, │
│ scoped) │ │ tier cache, │
│ │ │ OTPs) │
└─────────────┘ └───────────────┘
Real-time updates use Server-Sent Events (SSE), not WebSockets — see docs/architecture.md.
| Layer | Technology |
|---|---|
| Backend | FastAPI, SQLAlchemy (async), Alembic, Python 3.10+ |
| Frontend | React 18, Vite 5, Ant Design 5, Redux Toolkit, react-i18next |
| Database | MySQL 8 |
| Cache / Pub-Sub / Blocklist | Redis 7 |
| AI | Google Gemini 2.0 Flash + Ollama (optional local) |
| Auth | JWT (HttpOnly cookie) + Google OAuth 2.0 |
| Real-time | Server-Sent Events (SSE) |
| SMTP (configurable — any provider) |
- Docker & Docker Compose
- Git
git clone https://github.com/Chakrix-com/Swaya.me.git
cd Swaya.me
cp backend/.env.example backend/.envEdit backend/.env and fill in at minimum:
JWT_SECRET— any long random string (openssl rand -hex 32)GEMINI_KEY— Google AI Studio API key (free tier works)GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET— for Google OAuth (optional)SMTP_*— for email features (optional)
docker compose -f docker-compose.dev.yml up --buildThis starts MySQL, Redis, and the FastAPI backend with hot-reload.
cd frontend
npm install
npm run devFrontend: http://localhost:5173 API docs: http://localhost:8000/api/docs
docker exec swaya-dev-backend alembic upgrade headcd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # edit as above
alembic upgrade head
uvicorn main:app --reload --port 8000cd frontend
npm install
npm run devSwaya.me/
├── backend/
│ ├── main.py # FastAPI app entry point
│ ├── broker/api/routes.py # Central router (20 sub-routers)
│ ├── core/
│ │ ├── config/settings.py # All config (env-driven)
│ │ ├── ai/ # Gemini + Ollama integrations
│ │ └── security/ # JWT, OAuth, password hashing
│ ├── features/
│ │ └── quiz/ # Quiz, session, exam, poll services
│ ├── persistence/
│ │ ├── models/ # SQLAlchemy models
│ │ └── migrations/ # Alembic migrations
│ └── .env.example
├── frontend/
│ ├── src/
│ │ ├── App.jsx # Root routes + ProLayout
│ │ ├── features/ # Feature components by domain
│ │ ├── services/api.js # All API calls (single source)
│ │ └── locales/ # 11× i18n JSON files
│ └── .env.production
├── docs/ # Documentation
│ ├── architecture.md
│ ├── features.md
│ ├── tech-choices.md
│ ├── multi-tenancy.md
│ ├── deployment.md
│ └── security.md
└── scripts/ # Load tests, regression scripts
| Document | Description |
|---|---|
| docs/architecture.md | System overview, SSE realtime flow, service layer, data model |
| docs/features.md | All activity types, AI features, export, admin tools |
| docs/tech-choices.md | Why FastAPI, MySQL, SSE, cookies — with tradeoffs |
| docs/multi-tenancy.md | DB isolation, roles, tier system, public endpoints |
| docs/deployment.md | Production setup: Nginx, systemd, Alembic, env vars |
| docs/security.md | HttpOnly cookies, JWT revocation, rate limiting, sanitization |
Copy backend/.env.example and fill in the values. Key variables:
| Variable | Required | Description |
|---|---|---|
DB_HOST / DB_NAME / DB_USER / DB_PASSWORD |
Yes | MySQL connection |
REDIS_HOST / REDIS_PORT |
Yes | Redis connection |
JWT_SECRET |
Yes | Random secret for JWT signing |
GEMINI_KEY |
For AI features | Google AI Studio API key |
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET |
For Google login | OAuth 2.0 credentials |
SMTP_HOST / SMTP_USER / SMTP_PASSWORD |
For email | Any SMTP provider |
SMTP_FROM_EMAIL / SMTP_FROM_NAME |
For email | Sender identity |
FRONTEND_URL |
For email links | Your deployed frontend URL |
OLLAMA_BASE_URL |
Optional | Local Ollama for offline AI |
cd backend
source .venv/bin/activate
pytestInteractive Swagger UI is available at /api/docs when the backend is running.
- WebRTC-based video proctoring (replacing client-side snapshot approach)
- Live quiz team mode (group participants into teams)
- Poll scheduling (future open/close time)
- Webhook support for exam completion events
- S3/R2 object storage for uploads (currently local filesystem)
- Expanded export: Google Slides, CSV with raw timings
See CONTRIBUTING.md for development setup, branch conventions, migration workflow, and PR guidelines.
Apache 2.0 — see LICENSE.
Copyright 2026 Chakrix / Nishant