Q-Learn

Adaptive multi-agent AI platform for interactive quantum computing education.

Q-Learn is a startup product that combines AI tutoring, personalized learning, quantum circuit construction, Qiskit simulation, and adaptive assessment into a single interactive quantum learning laboratory.

Originally built for Smart India Hackathon 2026 — Problem Statement SIH2614.

---

What makes it different

Most quantum learning tools are either static docs or a bare Qiskit playground. Q-Learn closes the loop:

LEARN → BUILD → SIMULATE → OBSERVE → EXPLAIN → PRACTICE → EVALUATE → ADAPT

Core feature — "Explain My Circuit": A student builds a circuit. Q-Learn explains what each gate does, how the quantum state changes, the mathematical transformation, why the measurement probabilities look that way, what mistakes were made, and what to learn next.

The system connects: MATHEMATICS ↔ QUANTUM STATE ↔ CIRCUIT ↔ CODE ↔ SIMULATION ↔ MEASUREMENT

---

Tech Stack

Layer	Technology
Frontend	Next.js 14 · TypeScript · React Flow · Tailwind · Zustand
Backend	FastAPI · Python 3.11 · SQLAlchemy 2.x · Alembic
AI / Agents	LangGraph · LangChain · LlamaIndex · pgvector · Sentence Transformers
Quantum	Qiskit Aer (via Vercel Sandbox microVM)
Database	Supabase (PostgreSQL + pgvector + Auth + Realtime)
Execution	Vercel Sandbox — isolated microVM for student code and Qiskit
Payments	Razorpay (freemium + Pro subscriptions)
Hosting	Vercel (frontend) · InstaCloud (FastAPI) · Supabase Cloud
CI/CD	GitHub Actions

---

Architecture

Three-tier: Presentation (Vercel) → Application (InstaCloud/FastAPI) → Data & Infrastructure (Supabase + Vercel Sandbox)

Key design decisions:

• No WebSocket endpoints on FastAPI — real-time events flow via Supabase Realtime pub/sub; FastAPI publishes, frontend subscribes via Supabase JS SDK
• No in-process Qiskit — all circuit simulation and student code runs inside a Vercel Sandbox microVM (SandboxRunner.run_python() → vercel.sandbox.create_sandbox()); FastAPI stays I/O-bound
• Agent state in PostgreSQL — LangGraph uses AsyncPostgresSaver; agent sessions survive restarts and scale across replicas
• No Redis in Phase 0–1 — deferred until profiling shows a specific hot path

Full detail: Architecture.md · docs/

---

Monetization

Freemium + Razorpay subscriptions (Indian market — UPI, cards, netbanking).

Feature	Free	Pro
Full curriculum (all 12 levels)	✅	✅
All lessons	✅	✅
AI Tutor	—	✅
Qiskit circuit execution	—	✅
Adaptive quiz generation	—	✅

The paywall aligns with cost drivers (LLM calls + Vercel Sandbox forks). Full billing spec: docs/payment-system-design.md

---

Quick Start (Development)

Prerequisites: Node.js 20+, Python 3.11+, pnpm, Docker & Docker Compose v2+, Supabase account, Vercel account (Hobby plan)

git clone <repo-url>
cd qlearn

cp .env.example .env
# fill in: SUPABASE_URL, SUPABASE_SERVICE_KEY, SUPABASE_JWT_SECRET, DATABASE_URL,
#          VERCEL_TOKEN, RAZORPAY_KEY_ID, RAZORPAY_KEY_SECRET, LLM_PRIMARY_MODEL
# Team members: see docs/onboarding.md for which values are shared vs. local.

docker compose up --build
# Frontend  →  http://localhost:3000
# API       →  http://localhost:8000
# API docs  →  http://localhost:8000/docs

Run migrations:

cd backend
alembic upgrade head

New to the team? See docs/onboarding.md for the shared-Supabase setup. See docs/infrastructure.md for the full environment variable reference and production deployment guide.

---

Live deployment

Service	URL
API (InstaCloud, production)	https://prod-main-api-de88c5-207as5mthww.compute.instacloud-edge.com
Health check	https://prod-main-api-de88c5-207as5mthww.compute.instacloud-edge.com/health
API docs (Swagger)	https://prod-main-api-de88c5-207as5mthww.compute.instacloud-edge.com/docs

Frontend points at the API via NEXT_PUBLIC_API_URL. Deploy and operations runbook: docs/infrastructure.md.

---

Curriculum

12 levels from quantum intuition to Shor's algorithm. Each concept follows: Concept → Intuition → Mathematics → Circuit → Code → Simulation → Practice

---

Documentation

Document	Contents
Architecture.md	System diagram, layer summary, engineering rules
Project.md	Full product spec, agent architecture, learning model
Development.md	Phases, MVP scope, testing strategy, getting started
docs/frontend-layer.md	VS Code shell, Zustand stores, design system
docs/agents.md	LangGraph agent topology, AsyncPostgresSaver
docs/quantum-execution.md	QiskitAerAdapter, Vercel Sandbox fork sequence
docs/rag-pipeline.md	BM25 + pgvector hybrid, reranker, knowledge base
docs/database.md	ERD, key tables, migration strategy
docs/security.md	Auth flow, RBAC, security controls
docs/payment-system-design.md

---

Development Phases

Phase	Scope	Timeline
0 — Foundation	Scaffold, auth, DB schema, Vercel Sandbox, Realtime, AsyncPostgresSaver	Week 1
1 — MVP	Curriculum, AI Tutor, circuit builder, Qiskit execution, quiz, payments	Week 2–3
2 — Agentic	LangGraph multi-agent system, coding challenges, PennyLane/Cirq adapters	Week 4–6
3 — Advanced	IBM Quantum hardware, 3D Bloch sphere, collaborative circuits	Week 7+

---

License

Q-Learn is a startup product — commercial freemium + subscription. Originally developed for Smart India Hackathon 2026 (SIH2614).