Adaptive Learning Assistant

An intelligent, gamified learning platform built with Next.js that adapts to your learning style, pace, and comprehension level. Designed as a high-fidelity proof of concept for hackathons.

📸 Screenshots

Landing Page	Onboarding

Dashboard	Chat Interface

Knowledge Graph / Gamification

🚀 Features

• Intelligent Adaptive Engine: Analyzes sentiment and difficulty to adjust teaching style on the fly.
• Gamification System: Earn XP, build daily streaks, and unlock badges for consistent learning and concept mastery.
• Spaced Repetition & Knowledge Graph: Visualizes your learning journey. Tracks which concepts you've mastered and which need review using a live, interactive node graph.
• Multi-Modal Learning: Switch between Teaching, Quizzing, Re-explaining, and Challenge modes seamlessly.
• Personalized Profiles: Adapts analogies and examples based on whether you are a visual, abstract, example-driven, or story-driven learner.
• Premium Dark UI: A refined, subtle dark theme built with Tailwind CSS and Framer Motion for smooth animations.

🛠 Tech Stack

• Framework: Next.js 16 (App Router)
• Styling: Tailwind CSS
• State Management: Zustand (with persist middleware for local storage)
• Animations: Framer Motion
• Graph Visualization: Cytoscape.js (via react-cytoscapejs)
• Icons: Lucide / Custom SVG

🚦 Getting Started

1. Clone the repository:

   git clone <repository-url>
   cd adaptive-learning

2. Install dependencies:

   npm install
   # or
   yarn install
   # or
   pnpm install

3. Set up Environment Variables: The project includes a .gitignore file that safely ignores .env, .env.local, and other environment files to prevent accidental commits of sensitive keys.

   Create a .env.local file in the root directory and add the necessary API keys. Currently, the project uses a simulated AI backend, but it's structured to easily connect to a real LLM provider.

   # .env.local
   
   # ─── LLM Providers (Required for production AI features) ───
   # If using OpenAI:
   OPENAI_API_KEY="your_openai_api_key_here"
   
   # If using Anthropic (Claude):
   ANTHROPIC_API_KEY="your_anthropic_api_key_here"
   
   # If using Google Gemini:
   GEMINI_API_KEY="your_gemini_api_key_here"
   
   # ─── Database / Persistence (Optional for Future Use) ───
   # If migrating from localStorage to a real database (e.g. Supabase or Postgres)
   # DATABASE_URL="your_database_connection_string"

4. Run the development server:

   npm run dev
   # or
   yarn dev

5. Open http://localhost:3000 with your browser to see the result.

🐳 Docker & Cloud Run Deployment

This project is configured with a multi-stage Dockerfile and uses Next.js standalone output mode to drastically reduce the container size. This makes it perfect for deployment to Google Cloud Run or any Docker-compatible hosting.

Build and Run Locally:

docker build -t adaptive-learning-app .
docker run -p 3000:3000 adaptive-learning-app

Deploying to Google Cloud Run: You can deploy directly from your source code using the Google Cloud CLI:

gcloud run deploy adaptive-learning \
  --source . \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated

(Make sure you have enabled the Cloud Run API and Cloud Build API in your GCP project).

🗺 Project Structure

• app/: Next.js App Router pages (Home, Chat, Dashboard, Onboarding).
• components/: Reusable React components (HelpBot, KnowledgeGraphViz).
• store/: Zustand state management (useStore.ts).
• app/api/chat/route.ts: The simulated AI backend logic (ready to be swapped with real LLM calls).

🎮 How it Works

1. Onboarding: Tell the system what you want to learn, your background, preferred style, and pace.
2. Dashboard: Your central hub. View your level, XP, streak, earned badges, and a breakdown of your concept mastery.
3. Chat: Interact with the AI tutor. Use natural language or quick-reply suggestions. Ask to be quizzed or challenged to earn more XP. The Knowledge Graph updates in real-time as you learn.