📖 Overview
The LMS System is a cutting-edge learning management platform designed to provide real-time, AI-driven teaching experiences. It allows users to create personalized learning companions with unique voices, styles, and subjects, enabling interactive and engaging learning sessions.
✨ Features
- Personalized Learning Companions: Build companions with customizable names, subjects, voices, and styles.
- Real-time Voice Conversations: Engage in natural and interactive voice-based learning sessions.
- Dynamic Subject Support: Covers a wide range of subjects, including Science, Maths, History, and more.
- Session History: Track completed lessons and review past sessions.
- Subscription Plans: Integrated pricing table for managing subscriptions.
🏗️ Architecture
The LMS System follows a modern, scalable architecture built on Next.js App Router:
- Frontend: Next.js 16 with React 19, TypeScript, and Tailwind CSS 4
- Authentication: Clerk for secure user management with custom theming
- Database: Supabase (PostgreSQL) with real-time capabilities
- Voice AI: Vapi.ai for real-time voice conversations
- Form Handling: React Hook Form + Zod for validation
- UI Components: Radix UI primitives with custom styling
Data Flow
User → Clerk Auth → Next.js App Router → Server Actions → Supabase
↓
Vapi.ai (Voice)
↓
Real-time Audio Stream
🔑 Key Implementations
1. Real-time Voice Conversations
- Vapi.ai Integration: Implemented in CompanionComponent.tsx
- Uses WebSocket for low-latency voice streaming
- Handles call status (CONNECTING, ACTIVE, FINISHED)
- Speech detection with visual feedback (Lottie animations)
2. Server Actions & Database
- CRUD Operations: companion.actions.ts
- Secure data access with Clerk + Supabase integration
- Real-time path revalidation for instant UI updates
- Bookmark system with user-specific filtering
3. Form Validation
- Zod Schema: Comprehensive validation in CompanionForm.tsx
- Real-time error feedback
- Type-safe form handling with React Hook Form
4. Authentication Flow
- Clerk Integration: Custom appearance with primary color
#fe5933
- Protected routes with server-side auth checks
- Token-based Supabase access
🧠 Challenges & Solutions
Challenge 1: Real-time Voice State Management
Problem: Managing multiple voice states (connecting, speaking, muted) and syncing with UI.
Solution: Implemented enum-based state machine with useEffect hooks for event listeners. Used Lottie animations for visual feedback during speech.
Challenge 2: Clerk + Supabase Authentication
Problem: Connecting Clerk's JWT tokens with Supabase for secure database access.
Solution: Created custom Supabase client with async token getter that retrieves Clerk's token server-side.
Challenge 3: Form Data Persistence
Problem: Ensuring companion data is saved correctly before redirecting.
Solution: Used Server Actions with proper error handling and redirect after successful creation.
👨💻 My Contributions
Core Features Implemented
- Companion Creation System: Full CRUD with form validation
- Voice Chat Interface: Real-time audio with Vapi.ai integration
- Session History: Tracking and storing completed lessons
- Search & Filter: Subject-based filtering with Supabase queries
- Bookmark System: Save favorite companions
Technical Highlights
- Built reusable UI components with Radix UI primitives
- Implemented type-safe database operations with TypeScript
- Optimized performance with Next.js caching and revalidation
- Created responsive design with Tailwind CSS
Key Files Created/Modified
🗂️ Project Structure
The project is built using Next.js and follows a modular structure:
app/: Contains the main application pages and layouts.
companions/: Pages for managing and interacting with companions.
subscription/: Subscription management page.
layout.tsx: Root layout with global styles and navigation.
components/: Reusable UI components such as Navbar, CompanionForm, and CTA.
constants/: Stores static data like subjects, colors, and voices.
lib/: Utility functions and API integrations.
public/: Static assets like images and icons.
types/: TypeScript type definitions for the project.
⚙️ Installation
- Clone the repository:
git clone <repository-url>
- Navigate to the project directory:
cd lms_system
- Install dependencies:
npm install
- Set up environment variables in
.env.local:
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY
CLERK_SECRET_KEY=YOUR_SECRET_KEY
- Run the development server:
npm run dev
🚀 Usage
- Build a Companion: Navigate to
/companions/new to create a new learning companion.
- Start a Session: Select a companion and begin a real-time voice session.
- Manage Subscriptions: Visit
/subscription to view and manage subscription plans.
🤝 Contributing
Contributions are welcome! Please fork the repository and submit a pull request with your changes.
📜 License
This project is licensed under the MIT License. See the LICENSE file for details.