An intelligent learning system that diagnoses why students fail by analyzing concept dependencies and provides personalized learning paths using visual knowledge graphs and AI assistance.
Stop wondering why you got it wrong. Start understanding why.
Move from:
"You got this wrong"
To:
"You got this wrong because you missed concept X, which depends on Y"
AdaptIQ is not just another quiz platform. It's a structured diagnostic system that understands how knowledge connects and identifies exactly where your learning breaks down.
- Landing Page:
/landing- Product overview and value proposition - Dashboard:
/- Your learning hub with progress stats - Practice:
/practice- Answer questions and get diagnosed - Knowledge Map:
/knowledge-map- Visual concept dependency graph - Progress:
/progress- Track your learning journey
A predefined structured knowledge graph where:
- Nodes represent concepts (e.g., Force, Mass, Acceleration)
- Edges represent dependencies/prerequisites
- Visual status indicators: Green (mastered), Yellow (weak), Red (missing)
- Curated question bank with difficulty levels (easy, medium, hard)
- Questions tagged with related concepts
- Instant feedback with detailed explanations
- Root cause analysis for incorrect answers
When a student answers incorrectly:
- Maps the error to specific concepts
- Traces prerequisite chain (1-2 levels deep)
- Identifies missing concepts and probable root causes
- Suggests personalized learning paths
- Interactive graph visualization using SVG
- Pan/zoom controls for exploration
- Click nodes for concept details
- Visual dependency highlighting on hover
- Color-coded progress indicators
- Context-aware chat assistant
- Explains concepts and mistakes
- Suggests what to study next
- Quick action buttons for common queries
- Accuracy metrics over time
- Concept mastery breakdown (pie chart)
- Individual concept progress bars
- Learning insights and achievements
| Layer | Technology |
|---|---|
| Framework | Next.js 16 (App Router) |
| Styling | Tailwind CSS + shadcn/ui |
| Charts | Recharts |
| Graph Visualization | Custom SVG-based component |
| Typography | Plus Jakarta Sans |
| Icons | Lucide React |
adaptiq/
├── app/
│ ├── layout.tsx # Root layout with fonts and metadata
│ ├── page.tsx # Dashboard page
│ ├── globals.css # Design system tokens
│ ├── landing/
│ │ └── page.tsx # Marketing landing page
│ ├── practice/
│ │ └── page.tsx # Practice session with questions
│ ├── knowledge-map/
│ │ └── page.tsx # Interactive knowledge graph
│ └── progress/
│ └── page.tsx # Progress tracking and insights
├── components/
│ ├── navbar.tsx # Navigation component
│ ├── stat-card.tsx # Statistics display card
│ ├── concept-card.tsx # Concept information card
│ ├── concept-badge.tsx # Status badge (mastered/weak/missing)
│ ├── question-card.tsx # MCQ question component
│ ├── diagnosis-panel.tsx # Root cause analysis display
│ ├── ai-chat-panel.tsx # AI assistant chat interface
│ └── knowledge-graph.tsx # SVG-based graph visualization
├── lib/
│ ├── types.ts # TypeScript type definitions
│ ├── data.ts # Mock data and utility functions
│ └── utils.ts # Helper utilities
└── README.md
| Color | Hex | Usage |
|---|---|---|
| Primary | #2563EB |
Intelligent blue - main actions |
| Secondary | #38BDF8 |
Light blue highlights |
| Background | #F8FAFC |
Page background |
| Surface | #FFFFFF |
Cards and surfaces |
| Success | #22C55E |
Mastered concepts |
| Warning | #F59E0B |
Weak concepts |
| Danger | #EF4444 |
Missing concepts |
| Text Primary | #0F172A |
Main text |
| Text Muted | #64748B |
Secondary text |
| Border | #E2E8F0 |
Borders and dividers |
- Font: Plus Jakarta Sans (fallback: Inter, sans-serif)
- H1: 40-48px, weight 700
- H2: 28-32px, weight 600
- H3: 20-24px, weight 600
- Body: 16px, weight 400-500
- Caption: 12-14px, weight 400
- Gap system: 8px base scale (8 / 12 / 16 / 24 / 32)
- Card padding: 20-24px
- Section padding: 64-96px
- Max width: 1200px (dashboard), 1400px (graph view)
- Cards: 16px
- Buttons: 10px
- Inputs: 8px
// Core domain types
interface Concept {
id: string;
name: string;
subject: string;
chapter: string;
description: string;
status?: 'mastered' | 'weak' | 'missing';
accuracy?: number;
}
interface ConceptDependency {
id: string;
parentConceptId: string;
childConceptId: string;
}
interface Question {
id: string;
questionText: string;
options: string[];
correctAnswer: string;
difficulty: 'easy' | 'medium' | 'hard';
explanation: string;
conceptIds: string[];
}
interface UserConceptProgress {
id: string;
userId: string;
conceptId: string;
accuracy: number;
confidenceLevel: 'low' | 'medium' | 'high';
lastUpdated: Date;
}- View progress summary and stats
- See weak concepts that need attention
- Get suggested next topic
- Start practice session
- Answer MCQ questions
- Get instant feedback
- View explanations for correct answers
- See root cause analysis for incorrect answers
- Get AI-powered assistance
- View session summary on completion
- Explore concept graph visually
- Click nodes to see details
- View prerequisites and dependents
- Navigate to practice for specific concepts
- Switch between graph and list views
- View accuracy trends over time
- See mastery distribution
- Review individual concept progress
- Get personalized learning insights
- Project setup with Next.js
- Design system implementation
- Core UI components
- Mock data for Physics chapter
- Basic navigation
- Question card component
- Answer submission flow
- Feedback display
- Explanation rendering
- Error to concept mapping
- Prerequisite chain tracing
- Root cause panel
- Suggested path display
- SVG-based visualization
- Node color coding
- Interactive pan/zoom
- Concept detail panel
- Chat panel UI
- Quick action buttons
- Context-aware suggestions
- Real AI API integration
- Accuracy charts
- Concept breakdown
- Learning insights
- Trend visualization
- Database integration (Supabase/PostgreSQL)
- User authentication
- Multi-subject support
- Full syllabus coverage
- Adaptive learning paths
- AI-generated questions
- Spaced repetition engine
- Mobile app
- Teacher dashboard
- Student collaboration features
- Node.js 18+
- pnpm (recommended) or npm
# Clone the repository
git clone <repository-url>
# Navigate to project directory
cd smart-learning-graph
# Install dependencies
pnpm install
# Start development server
pnpm devOpen http://localhost:3000 to view the application.
You can send reminder emails to users who are inactive:
- First reminder after 2 days of inactivity
- Then reminder every 7 days while still inactive
Run:
scripts/sql/create_reminder_state_table.sql
Add these in your .env.local (and production env):
NEXT_PUBLIC_SUPABASE_URL=...
NEXT_PUBLIC_SUPABASE_ANON_KEY=...
SUPABASE_SERVICE_ROLE_KEY=...
RESEND_API_KEY=...
REMINDER_FROM_EMAIL="AdaptIQ <noreply@yourdomain.com>"
REMINDER_APP_URL="http://localhost:3000"
REMINDER_JOB_SECRET=your-strong-secretEndpoint:
POST /api/jobs/send-inactive-reminders
Auth header required:
Authorization: Bearer <REMINDER_JOB_SECRET>
Example:
curl -X POST http://localhost:3000/api/jobs/send-inactive-reminders \
-H "Authorization: Bearer your-strong-secret"Dry run (no emails sent, only evaluation):
curl -X POST "http://localhost:3000/api/jobs/send-inactive-reminders?dryRun=1" \
-H "Authorization: Bearer your-strong-secret"Run this endpoint on a daily schedule (e.g., Vercel Cron, GitHub Action, server cron).
The route itself handles the 2-day first reminder and then 7-day repeat cadence.
AdaptIQ now supports structured memory + reasoning via Hindsight to retain learning events and produce context-aware memory insights.
- Quiz outcomes (
correct/incorrect, concept, subject/chapter) - Diagnosis events for incorrect answers
- Recommendation accept events
- Concept interactions (knowledge-map selection, chat interactions, profile switches)
- Progress snapshots (dashboard/progress page)
- Reminder send events (from reminder job)
Add these to .env.local (and production):
HINDSIGHT_API_URL=https://hindsight.vectorize.io
HINDSIGHT_API_KEY=... # optional if your deployment is public/no-auth
HINDSIGHT_BANK_PREFIX=adaptiq-user-
POST /api/hindsight/event
Retains one structured event to Hindsight. -
POST /api/hindsight/insights
Runs recall + reflect to return a short memory-grounded insight for chat.
If Hindsight env vars are missing, these routes safely return skipped: hindsight-disabled.
When Hindsight is enabled, inactivity reminders attempt to use reflect for a short personalized nudge line.
If unavailable, reminders automatically fall back to a generic nudge.
To run the app with full realtime syllabus parity (same scope as lib/data static catalog), use:
- Apply realtime catalog schema:
scripts/004_create_realtime_catalog_schema.sql
- Sync full catalog from
lib/data.tsto Supabase:
pnpm sync:catalogThis imports:
- profiles (school + btech)
- subjects, chapters, modules
- concepts + dependency graph
- questions + quizzes
- Start app:
pnpm devThe app will read from realtime catalog tables when present, with static fallback if catalog data is missing.
- Primary: Class 9-10 students (Science)
- Focus: Students struggling with:
- Concept clarity
- Weak fundamentals
- Fragmented knowledge
- One subject: Physics
- One chapter: Force & Laws of Motion
- Pre-built concept graph with 10 concepts
- Curated question bank (8+ questions)
- Basic diagnosis with 1-2 level dependency tracing
This product is NOT:
"Just practice questions + AI"
This product IS:
A structured system that understands knowledge and student learning gaps
The core innovation lies in the Diagnosis Engine that traces concept dependencies to identify the root cause of learning difficulties, providing actionable insights rather than just right/wrong feedback.
MIT
Contributions are welcome! Please read the contributing guidelines before submitting pull requests.