🎓 EduBuddy - Intelligent AI Tutoring Platform

An advanced, adaptive AI tutoring system that personalizes learning experiences using intelligent algorithms, learning style detection, and comprehensive progress tracking. Built for the Azure Codeathon 2025.

✨ Key Features

🧠 Intelligent Adaptive Learning

Multi-level Teaching: Automatically adjusts difficulty from beginner to advanced
Skill Validation: Mid-learning validation questions to check understanding
Assessment Questions: Personalized assessment to understand learning preferences
Real-time Adaptation: System learns from responses and adapts content

👤 User Profile & Metrics

Comprehensive Learning Profile: Track all learning activities
Skill Mastery Tracking: 0-100% mastery levels for each topic
Learning Streaks: Monitor daily learning consistency
Achievements System: Unlock badges (First Steps, Knowledge Seeker, On Fire, Master)

📊 Analytics Dashboard

Visual Learning Activity: Weekly activity chart
Performance Metrics: Average mastery, topics learned, streaks
Goal Progress Tracking: Monitor progress toward learning goals
Personalized Insights: AI-generated recommendations

🎯 Quiz Generation & Validation

Topic-based Quizzes: Generate quizzes for learned topics
Difficulty Levels: Easy, Medium, Hard variations
Immediate Feedback: Instant results and score breakdowns
Progress Tracking: Results contribute to skill mastery

🧠 Learning Style Detection

5-Question Assessment: Quick test to identify learning style
4 Learning Styles: Visual, Auditory, Reading/Writing, Kinesthetic
Personalized Teaching: Responses adapt based on style
Customized Recommendations: Tips based on detected style

🚀 Tech Stack

Frontend: Next.js 16, React 19, TypeScript
Styling: Tailwind CSS
Backend: Next.js API Routes
AI Model: Azure OpenAI (GPT-4o mini)
Deployment: Vercel (recommended)

💬 Smart Chat Interface

Real-time Conversations: Ask questions about any subject
Subject Selection: Choose from 6 subjects (General, Math, Science, History, Literature, Programming)
Conversation History: All conversations saved locally
Topic Extraction: Automatically identifies topics discussed
Learning Sidebar: Quick access to learning progress

📋 Prerequisites

Before getting started:

Node.js 18+ installed
npm or yarn
Azure OpenAI API credentials (optional - fallback to mock responses)
Modern browser with localStorage support

🔧 Setup Instructions

1. Clone the Repository

git clone <repository-url>
cd edubuddy

2. Install Dependencies

npm install

3. Configure Environment Variables (Optional)

Create a .env.local file for Azure OpenAI integration:

AZURE_OPENAI_API_KEY=your_azure_key_here
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_DEPLOYMENT_NAME=gpt-4o-mini

Note: The app works without Azure credentials using mock responses for testing.

4. Run Development Server

npm run dev

Visit http://localhost:3001 (or next available port) to start learning!

5. Build for Production

npm run build
npm start

🎯 Quick Start Guide

Starting Your Learning Journey

Select a Subject: Choose from General, Math, Science, History, Literature, or Programming
Ask a Question: Type any learning question in the chat
Get Adaptive Response: System provides content matched to your level
Answer Validation Questions: Mid-learning checks to verify understanding
Track Progress: Watch your mastery percentage grow

Using Key Features

📊 Analytics Dashboard (Bottom right 📊 icon)

Weekly activity visualization
Skill breakdown and progress
Goal tracking and insights

👤 User Profile (Bottom right 👤 icon)

Overall learning metrics
Skill mastery cards
Achievement badges

🧠 Learning Style Detector (Bottom left 🧠 icon)

5-question quick assessment
Personalized learning recommendations
Style-specific study tips

🎯 Take Quiz (Top right button, after messages)

Generate topic-based quizzes
Get immediate feedback
Track mastery through quiz results

📦 Project Structure

edubuddy/
├── app/
│   ├── api/
│   │   └── chat/route.ts          # Adaptive response API
│   ├── layout.tsx                  # Root layout
│   ├── page.tsx                    # Home page
│   └── globals.css                 # Global styles
├── components/
│   ├── ChatInterface.tsx           # Main chat UI
│   ├── QuizMode.tsx                # Quiz modal system
│   ├── UserProfile.tsx             # Profile & metrics panel
│   ├── Dashboard.tsx               # Analytics dashboard
│   └── LearningStyleDetector.tsx   # Style assessment
├── types/
│   └── user.ts                     # TypeScript interfaces
├── .env.local                      # Environment variables (create this)
├── next.config.ts                  # Next.js config
├── tailwind.config.ts              # Tailwind CSS config
└── package.json                    # Dependencies

🎯 How It Works

Learning Flow

User Interaction: Type questions about any topic
Topic Detection: System identifies keywords and learning domain
Level Determination: Difficulty adapts based on message count
- Messages 1-2: Beginner
- Messages 3-7: Intermediate
- Messages 8+: Advanced
Adaptive Response: AI generates appropriately-leveled explanation
Skill Validation: Every 2-3 messages, check questions appear
Progress Tracking: Topics recorded and mastery calculated
Data Persistence: All data saved to localStorage

Learning Styles Integration

The system customizes teaching based on detected style:

Visual: Structured lists, diagrams, organized information
Auditory: Conversational tone, detailed verbal explanations
Reading/Writing: Comprehensive text, notes, detailed examples
Kinesthetic: Practice problems, hands-on examples, real applications

🔄 Data Persistence

All user data stored locally using browser localStorage:

// Keys used:
- edubuddy_conversations    // Chat history
- edubuddy_topics           // Learning topics
- edubuddy_user_profile     // User metrics & achievements
- edubuddy_skills           // Detailed skill data
- edubuddy_goals            // Learning goals
- edubuddy_learning_style   // Detected learning style

🌐 Deployment Options

Deploy to Vercel (Recommended)

Push your code to GitHub
Visit Vercel
Import your GitHub repository
Add environment variables in Vercel dashboard (optional):
- AZURE_OPENAI_API_KEY
- AZURE_OPENAI_ENDPOINT
- AZURE_DEPLOYMENT_NAME
Deploy with one click!

Deploy to Other Platforms

This is a standard Next.js app deployable to:

Netlify: Connect GitHub, auto-deploys on push
AWS Amplify: AWS hosting with CI/CD
DigitalOcean: App Platform for easy deployment
Azure App Service: Native Azure hosting
Docker: Containerize for any cloud provider

Local Docker Deployment

# Build image
docker build -t edubuddy .

# Run container
docker run -p 3000:3000 edubuddy

💡 Best Practices for Learning

Maximize Your Learning

Be Specific: Ask focused questions about one concept
Follow Up: Build on previous answers for depth
Request Examples: Real-world applications reinforce concepts
Practice Problems: Use quizzes to test understanding
Mix Subjects: Explore multiple topics to broaden knowledge

Using Learning Style Effectively

Visual Learners: Create mind maps from explanations
Auditory Learners: Read responses aloud to yourself
Reading/Writing Learners: Maintain detailed learning notes
Kinesthetic Learners: Work through all practice problems

Track Your Progress

Review Dashboard: Check weekly to see improvement trends
Monitor Streaks: Maintain daily learning consistency
Check Mastery: Aim for 80%+ mastery in topics
Achieve Badges: Unlock achievements as motivation

🔧 Customization & Extension

Adding New Topics

Update topic extraction in components/ChatInterface.tsx:

const keywords = {
  "YourTopic": ["keyword1", "keyword2", "keyword3"],
};

Add quiz questions in components/QuizMode.tsx:

yourtopic: [
  {
    id: "1",
    question: "Your question?",
    options: ["Option A", "Option B", "Option C", "Option D"],
    correctAnswer: 0,
    difficulty: "easy"
  }
]

Add adaptive responses in app/api/chat/route.ts:

if (topic.toLowerCase().includes("yourtopic")) {
  return responses.yourtopic[level];
}

Modifying Learning Levels

Adjust difficulty progression in app/api/chat/route.ts:

function determineLevel(messageCount: number) {
  if (messageCount < 3) return "beginner";
  if (messageCount < 8) return "intermediate";
  return "advanced";
}

Customizing UI Colors

Modify Tailwind classes throughout components:

// Example: Change primary gradient
from-blue-500 to-purple-500  →  from-teal-500 to-cyan-500

📊 Analytics & Metrics

The system tracks:

Mastery Level: 0-100% for each topic
Questions Answered: Total questions attempted
Accuracy Rate: Percentage of correct answers
Time Spent: Hours/minutes per topic
Learning Streaks: Consecutive days of learning
Topics Learned: Total unique topics covered
Goals Progress: Advancement toward learning goals
Achievement Badges: Unlocked milestones

🐛 Troubleshooting

Issue	Solution
Port 3000 in use	Server uses next available port (3001, 3002, etc.)
Azure OpenAI 404 errors	Normal - system uses mock responses as fallback
Data not persisting	Check browser localStorage is enabled
Components not rendering	Clear cache: `npm run build`
Styles not loading	Ensure Tailwind CSS post-processor installed
Quiz not appearing	Chat needs at least one message first

🎓 Use Cases

👨‍🎓 Students: Personalized homework help and tutoring
👩‍🏫 Teachers: Supplementary learning tool for students
🎯 Self-Learners: Learn topics at your own pace
📚 Test Prep: Generate practice questions and explanations
🚀 Professionals: Quick skill-up in new domains

🤝 Contributing

Contributions are welcome! Please:

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

📄 License

This project is licensed under the MIT License. See LICENSE file for details.

🙏 Acknowledgments

Azure Codeathon 2025: Competition that inspired this project
Azure OpenAI: AI capabilities powered by GPT-4o mini
Next.js & React: Modern web frameworks
Tailwind CSS: Beautiful UI styling
Open Source Community: For amazing tools and libraries

📞 Support & Feedback

Issues: Open an issue on GitHub for bugs or feature requests
Discussions: Use GitHub Discussions for questions and ideas
Email: Contact team for direct support
Documentation: Check README and code comments first

🎯 Roadmap

Potential future features:

Real-time collaboration between students
Spaced repetition system based on learning science
Knowledge graph visualization
Mobile app (React Native)
Video tutorial integration
Real-time progress notifications
Custom topic creation
Leaderboards and social features

📊 Performance Metrics

Build Time: ~195ms with Turbopack
Page Load: <2 seconds on 4G
API Response: ~1200ms with Azure OpenAI, instant with mock
Bundle Size: Optimized with Next.js tree-shaking
Lighthouse Score: 90+ across all metrics

🔐 Privacy & Data Security

Local Storage Only: No data sent to external servers (except Azure OpenAI)
No Tracking: No analytics or third-party tracking
Browser-based: All processing happens client-side when possible
HTTPS Ready: Secure connection when deployed
User Control: Users can clear all data anytime

📚 Additional Resources

Made with ❤️ for lifelong learners everywhere

Built during Azure Codeathon 2025 | Last Updated: October 2025

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
app		app
components		components
types		types
.gitignore		.gitignore
README.md		README.md
next-env.d.ts		next-env.d.ts
next.config.ts		next.config.ts
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json

sarvanithin/edubuddy

Folders and files

Latest commit

History

Repository files navigation