🚀 Live Demo: https://tutor-chatbot-eight.vercel.app/
An AI-powered Subject Tutor Chatbot built with Next.js 16 and Google Gemini 2.5 Flash API, featuring multimodal input support (text, voice, images), adaptive teaching modes, and intelligent conversation management.
Built with production-ready features including rate limiting, lazy loading, strict TypeScript, and comprehensive error handling.
Multiple Tutor Modes
- Explain Mode – Clear step-by-step teaching with examples
- Socratic Mode – Guided learning through thought-provoking questions
- Revision Mode – Summaries, patterns, and practice problems
- Exam-Focused Mode – Concise, exam-ready answers
Subject-Agnostic Learning
- Physics, Mathematics, Biology, History, Computer Science, or any subject
- Context-aware responses based on selected subject and level
- Intelligent conversation continuity with session memory
Voice Input
- Real-time 48-bar audio visualizer
- Web Audio API integration
- Auto-recording with visual feedback
File Upload
- Drag-and-drop image upload
- Image preview with hover animations
- Multimodal analysis (images + text combined)
Text Chat
- Standard text input with file attachment support
- Markdown rendering with LaTeX math support
- Code syntax highlighting
- Real-time Streaming – Token-by-token response generation
- Character Animation – Smooth typewriter effect using Framer Motion
- Session Management – Maintains conversation context
- Notes Panel – Take and export study notes during chat
- Error Recovery – Preserves partial responses on errors
- Modern Design – Clean, distraction-free chat interface
- Dark Mode – System preference detection with manual toggle
- Responsive – Mobile, tablet, and desktop optimized
- Rate Limited Demo – 10 requests per user per 24 hours
- Demo Banner – Shows remaining requests for transparency
- Next.js 16.1.1 with Turbopack
- React 19 with Server & Client Components
- TypeScript (strict mode, zero
anytypes) - Tailwind CSS for styling
- shadcn/ui component library
- Framer Motion 12 for animations
- next-themes for dark mode
- Next.js API Routes (streaming endpoints)
- Google Gemini 2.5 Flash AI model
- Zustand for state management
- Web Audio API for voice visualizer
- Vercel deployment
- IP-based rate limiting (10 requests/24h)
- Lazy loading with dynamic imports
- Environment-based configuration
🏗️ Project Structure tutor-chatbot/ ├── app/ │ ├── api/chat/route.ts # Gemini streaming API │ ├── layout.tsx # Root layout │ ├── page.tsx # Main chat UI │ └── globals.css # Global styles ├── components/ │ ├── ChatWindow.tsx │ ├── ChatInput.tsx
tutor-chatbot/
├── app/
│ ├── api/chat/stream/ # Streaming API endpoint
│ ├── demo/ # Component showcase
│ ├── layout.tsx # Root layout with providers
│ └── page.tsx # Main app (lazy loaded)
├── components/
│ ├── chat/ # Chat UI components
│ │ ├── chat-input.tsx
│ │ ├── message.tsx
│ │ ├── file-upload.tsx
│ │ ├── audio-input.tsx
│ │ └── tutor-mode-selector.tsx
│ ├── ui/ # shadcn/ui components
│ │ ├── ai-voice-input.tsx # 48-bar visualizer
│ │ ├── animated-text.tsx # Typewriter effect
│ │ └── ...
│ ├── notes/ # Notes panel
│ ├── tutor-interface-v2.tsx # Main chat interface
│ ├── demo-banner.tsx # Rate limit banner
│ └── theme-toggle.tsx # Dark mode toggle
├── lib/
│ ├── utils.ts # Utility functions
│ └── rate-limiter.ts # IP-based rate limiting
├── store/
│ └── session-store.ts # Zustand state management
├── hooks/
│ ├── useMemory.ts # Session memory hook
│ └── useSession.ts # Session management
├── types/
│ └── index.ts # TypeScript interfaces
└── __tests__/ # Jest test suite
- Node.js 18+
- npm/pnpm/yarn
- Google Gemini API Key (Get it free)
- Clone the repository
git clone https://github.com/yasharyas/Tutor-Chatbot.git
cd Tutor-Chatbot- Install dependencies
npm install- Set up environment variables
Create .env.local in the root directory:
GEMINI_API_KEY=your_gemini_api_key_here- Run the development server
npm run dev- Open in browser
http://localhost:3000
npm run build
npm startLive Demo: https://tutor-chatbot-eight.vercel.app/
Quick Deploy:
Manual Steps:
- Push your code to GitHub
- Go to vercel.com/new
- Import your repository
- Add environment variable:
GEMINI_API_KEY= your API key
- Deploy!
Note: The live demo has rate limiting (10 requests per user per 24 hours). Deploy your own version for unlimited access.
See DEPLOYMENT.md for detailed deployment instructions.
Open: 👉 http://localhost:3000
- Clear, patient teaching style
- Step-by-step breakdowns with examples
- Starts simple, adds complexity gradually
- Best for: Learning new concepts
- Guides through thought-provoking questions
- Never gives direct answers
- Encourages critical thinking
- Best for: Deep understanding
- Creates summaries and finds patterns
- Tests understanding with practice problems
- Consolidates knowledge
- Best for: Exam preparation
- Concise, exam-ready answers
- Highlights key concepts and common mistakes
- Direct and efficient
- Best for: Quick revision
- Select Your Subject: Enter your subject (e.g., "Physics", "Computer Science")
- Choose Your Level: Specify your level (e.g., "High School", "University")
- Pick a Mode: Choose the teaching style that fits your needs
- Start Chatting: Ask questions naturally!
- Click the microphone icon
- Speak your question
- The 48-bar visualizer shows your audio input
- Click stop when done
- Click the attachment icon or drag files
- Supports images (diagrams, screenshots, problems)
- AI analyzes images along with your text question
- Hover over files to see animated details
- Click the "Notes" tab
- Jot down important points during chat
- Export notes as text file
- Notes persist during session
- ✅ Lazy loading with dynamic imports
- ✅ Streaming responses (SSE)
- ✅ Optimized bundle size
- ✅ Server and Client Components separation
- ✅ Strict TypeScript mode
- ✅ Zero
anytypes - ✅ Proper interface definitions
- ✅ Type-safe API routes
- ✅ Preserves partial responses on error
- ✅ Specific error messages (rate limit, overload, etc.)
- ✅ Graceful degradation
- ✅ Network status detection
- ✅ Rate limiting for demo deployment
- ✅ Environment-based configuration
- ✅ Comprehensive test coverage
- ✅ Clean code with no verbose comments
Run the test suite:
npm testRun with coverage:
npm run test:coverage- API key stored securely in environment variables
- Rate limiting prevents abuse
- No user data collection
- Session-based memory (no database)
- Session-based history (no persistence)
- In-memory rate limiting (resets on server restart)
- Free tier API rate limits may apply
- Voice transcription not yet implemented
- Persistent chat history with database
- Voice-to-text transcription
- Text-to-speech responses
- Multi-language support
- User authentication
- Conversation export (PDF/Markdown)
Yash Arya
- GitHub: @yasharyas
- Email: yasharyas@proton.me
- Role: Full-stack development, UI/UX, API integration
Kuljot (Team Member)
- Collaboration on architecture and feature planning
MIT License - feel free to use this project for learning and personal projects.
- Next.js Team for the amazing framework
- Vercel for free hosting
- Google for Gemini API
- shadcn for the beautiful UI components
- Framer for Motion animations
⭐ If you find this project helpful, please give it a star!
🔗 Live Demo: https://tutor-chatbot-eight.vercel.app/
📚 Happy Learning! ✨