Next.js React TypeScript Supabase VAPI Clerk Tailwind CSS License

Revolutionize your learning with AI voice companions. Real-time voice conversations, personalized tutors, and gamified learning—all powered by cutting-edge AI. 🚀 Voice AI • 📊 Analytics • 🎨 Glassmorphism UI • 🔥 Streak Tracking

• 🗣️ Real-Time Voice Conversations - Natural, AI-powered tutoring sessions via VAPI SDK
• 🎯 Subject-Specific Companions - Create custom AI tutors for Math, Science, Coding, Languages, History, Economics
• 🎭 Personality Customization - Choose voice gender (Male/Female) and teaching style (Formal/Casual)
• 📝 Live Transcription - Real-time conversation capture with full session transcripts

• 📅 Activity Heatmap - GitHub-style learning visualization with weekly, monthly, and yearly views
• 🔥 Streak Counter - Track daily learning consistency and longest streaks
• 📉 Bar Charts & Calendars - Multi-view data visualization for insights
• 🏆 Gamification - Achievement badges and progress milestones

• ➕ Create Custom Companions - Multi-step form with topic, subject, voice, and duration selection
• 📚 Companion Library - Browse popular companions and recently completed sessions
• 💾 Bookmarking System - Save favorite companions for quick access
• 🔄 Reusable Templates - Share companion configurations via shareable links
• 🎨 Subject-Themed UI - Color-coded companions by subject (Math: Yellow, Science: Purple, etc.)

• ⚡ Next.js 15 - React 19, Server Components, Turbopack for blazing-fast performance
• 🎨 Glassmorphism UI - Frosted glass effects with Tailwind CSS 4.0
• 🌊 Framer Motion - Smooth animations and micro-interactions
• 🎞️ Lottie Animations - Loading states, success animations, and empty states

• 🔒 Clerk Authentication - Google OAuth, social login, and session management
• 🗄️ Supabase Backend - PostgreSQL database with real-time subscriptions
• 🚀 Edge-Optimized - Sentry error tracking and performance monitoring
• 🔄 Server-Side Caching - React Cache API for optimized data fetching
• 🛡️ Type-Safe - Full TypeScript coverage with Zod validation

┌─────────────────────────────────────────────────────────┐
│ Client Layer │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Next.js 15 │ │ React 19 │ │ Tailwind CSS │ │
│ │ App Router │ │ Components │ │ Styling │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────┘
 │
 ▼
┌─────────────────────────────────────────────────────────┐
│ Authentication Layer │
│ ┌──────────────┐ │
│ │ Clerk Auth │ │
│ │ OAuth 2.0 │ │
│ └──────────────┘ │
└─────────────────────────────────────────────────────────┘
 │
 ┌─────────────┴─────────────┐
 ▼ ▼
┌──────────────────────────┐ ┌──────────────────────────┐
│ Voice AI Layer │ │ Database Layer │
│ ┌────────────────────┐ │ │ ┌────────────────────┐ │
│ │ VAPI SDK │ │ │ │ Supabase │ │
│ │ - Voice Recognition│ │ │ │ - PostgreSQL DB │ │
│ │ - Text-to-Speech │ │ │ │ - Real-time APIs │ │
│ │ - Conversation AI │ │ │ │ - Storage Buckets │ │
│ └────────────────────┘ │ │ └────────────────────┘ │
└──────────────────────────┘ └──────────────────────────┘
 │ │
 └─────────────┬─────────────┘
 ▼
┌─────────────────────────────────────────────────────────┐
│ Monitoring Layer │
│ ┌──────────────┐ │
│ │ Sentry │ │
│ │ Error/Perf │ │
│ └──────────────┘ │
└─────────────────────────────────────────────────────────┘

Ensure you have the following installed:

• Node.js 18.0+ (Download) 🟢
• npm package manager 📦
• Git for version control 🔧
• Supabase account (Sign up) 🗄️
• Clerk account (Sign up) 🔐
• VAPI account (Sign up) 🎙️

1. Clone the repository

   git clone https://github.com/chayan-1906/IntelliCourse-Next.js.git
   cd IntelliCourse-Next.js

2. Install dependencies

   npm install

3. Configure environment variables

   Create a .env file in the root directory:

   cp .env.example .env

   Add the following variables:

   # Clerk Authentication
   NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxxxx
   CLERK_SECRET_KEY=sk_test_xxxxx
   # Clerk - Custom Auth
   NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
   NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL=/
   NEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL=/
   # Supabase Configuration
   NEXT_PUBLIC_SUPABASE_URL=https://xxxxx.supabase.co
   NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
   # VAPI Configuration
   NEXT_PUBLIC_VAPI_WEB_TOKEN=xxxxx-xxxxx-xxxxx-xxxxx
   # Sentry (Optional - for production monitoring)
   SENTRY_AUTH_TOKEN=xxxxx

4. Set up Supabase database

   Run the following SQL in your Supabase SQL Editor:

   -- Create companions table
   CREATE TABLE companions (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    name TEXT NOT NULL,
    subject TEXT NOT NULL,
    topic TEXT NOT NULL,
    voice TEXT NOT NULL,
    style TEXT NOT NULL,
    duration INTEGER NOT NULL,
    author TEXT NOT NULL,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
   );
   -- Create session_history table
   CREATE TABLE session_history (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    companion_id UUID REFERENCES companions(id) ON DELETE CASCADE,
    user_id TEXT NOT NULL,
    duration_minutes INTEGER DEFAULT 0,
    transcript TEXT,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    completed_at TIMESTAMPTZ
   );
   -- Create bookmarks table
   CREATE TABLE bookmarks (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    companion_id UUID REFERENCES companions(id) ON DELETE CASCADE,
    user_id TEXT NOT NULL,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    UNIQUE(companion_id, user_id)
   );
   -- Enable Row Level Security
   ALTER TABLE companions ENABLE ROW LEVEL SECURITY;
   ALTER TABLE session_history ENABLE ROW LEVEL SECURITY;
   ALTER TABLE bookmarks ENABLE ROW LEVEL SECURITY;
   -- Create policies (adjust based on your auth setup)
   CREATE POLICY "Enable read for all users" ON companions FOR SELECT USING (true);
   CREATE POLICY "Enable insert for authenticated users" ON companions FOR INSERT WITH CHECK (true);
   CREATE POLICY "Enable update for owner" ON companions FOR UPDATE USING (auth.uid() = author);
   CREATE POLICY "Enable delete for owner" ON companions FOR DELETE USING (auth.uid() = author);

5. Configure VAPI Assistant

   In your VAPI dashboard:

   • Create a new assistant
   • Configure voice settings (male/female options)
   • Set up system prompts for educational tutoring
   • Enable conversation transcription
   • Copy the Assistant ID to your .env

6. Run development server

   npm run dev

7. Open browser

   Navigate to http://localhost:3000 🎉

IntelliCourse-Next.js/
├── src/
│ ├── app/ # Next.js App Router
│ │ ├── api/ # API routes
│ │ │ └── sentry-example-api/ # Sentry integration
│ │ ├── companions/ # Companion pages
│ │ │ ├── [id]/ # Dynamic companion detail
│ │ │ │ ├── page.tsx # Session page
│ │ │ │ └── loading.tsx # Loading skeleton
│ │ │ ├── new/ # Create companion
│ │ │ └── page.tsx # Companions list
│ │ ├── my-journey/ # User analytics dashboard
│ │ ├── subscription/ # Subscription management
│ │ ├── sign-in/ # Authentication pages
│ │ ├── layout.tsx # Root layout with providers
│ │ ├── page.tsx # Home page
│ │ └── globals.css # Global styles
│ │
│ ├── components/ # Reusable components
│ │ ├── ui/ # Shadcn UI components
│ │ │ ├── button.tsx
│ │ │ ├── form.tsx
│ │ │ ├── input.tsx
│ │ │ ├── select.tsx
│ │ │ ├── skeleton.tsx
│ │ │ └── ...
│ │ ├── skeletons/ # Loading skeletons
│ │ │ ├── ActivityHeatmapSkeleton.tsx
│ │ │ ├── CompanionCardSkeleton.tsx
│ │ │ ├── SessionHistorySkeleton.tsx
│ │ │ └── ...
│ │ ├── ActivityHeatmap.tsx # Heatmap visualization
│ │ ├── AnimatedMyJourney.tsx # Animated dashboard
│ │ ├── AnimationModal.tsx # Loading/success modals
│ │ ├── CompanionCard.tsx # Companion display card
│ │ ├── CompanionComponent.tsx # Voice session handler
│ │ ├── CompanionForm.tsx # Multi-step creation form
│ │ ├── CompanionList.tsx # List with filtering
│ │ ├── MonthlyCalendarGrid.tsx # Calendar view
│ │ ├── Navbar.tsx # Navigation bar
│ │ ├── SessionHistory.tsx # Session log with export
│ │ ├── StreakCounter.tsx # Gamification component
│ │ ├── TranscriptViewer.tsx # Session transcript display
│ │ ├── WeeklyBarChart.tsx # Bar chart visualization
│ │ └── ...
│ │
│ ├── lib/ # Utility libraries
│ │ ├── actions/ # Server actions
│ │ │ └── companion.actions.ts # CRUD operations
│ │ ├── routes.ts # Route constants
│ │ ├── share.ts # Share functionality
│ │ ├── supabase.ts # Supabase client
│ │ ├── utils.ts # Utility functions
│ │ └── vapi.sdk.ts # VAPI SDK wrapper
│ │
│ ├── types/ # TypeScript definitions
│ │ ├── companion.ts # Companion types
│ │ ├── index.d.ts # Global types
│ │ ├── navigation.ts # Navigation types
│ │ └── vapi.d.ts # VAPI types
│ │
│ ├── hooks/ # Custom React hooks
│ │ ├── useAnimationModal.ts # Modal state management
│ │ └── useBreadcrumbs.ts # Navigation breadcrumbs
│ │
│ ├── config/ # Configuration files
│ │ ├── config.ts # App configuration
│ │ └── navigation.ts # Navigation config
│ │
│ ├── constants/ # App constants
│ │ ├── animations.ts # Lottie animation paths
│ │ ├── icons.ts # Icon mappings
│ │ ├── index.ts # General constants
│ │ └── soundwaves.json # Soundwave animation
│ │
│ ├── middleware.ts # Auth & route middleware
│ └── instrumentation.ts # Sentry instrumentation
│
├── public/ # Static assets
│ ├── animations/ # Lottie JSON files
│ │ ├── neural-network.json
│ │ └── no-data.json
│ ├── icons/ # SVG icons
│ │ ├── bookmark.svg
│ │ ├── mic-on.svg
│ │ ├── mic-off.svg
│ │ └── ...
│ └── images/ # Static images
│ ├── logo.svg
│ ├── cta.svg
│ └── limit.svg
│
├── .env # Environment variables (gitignored)
├── components.json # Shadcn UI config
├── next.config.ts # Next.js configuration
├── package.json # Dependencies
├── postcss.config.mjs # PostCSS config
├── tailwind.config.ts # Tailwind configuration
├── tsconfig.json # TypeScript config
├── sentry.server.config.ts # Sentry server config
├── sentry.edge.config.ts # Sentry edge config
└── README.md # The repository README

How it Works:

1. User creates a companion with subject, topic, voice, and style
2. Session starts via CompanionComponent.tsx using VAPI SDK
3. Real-time transcription captures conversation
4. Timer tracks session duration (auto-saved)
5. Transcript saved to Supabase on session end
6. Activity data updates the heatmap and streak counter

Key Components:

• CompanionComponent.tsx - Handles VAPI lifecycle, mic control, and state
• vapi.sdk.ts - VAPI client initialization and event handlers
• companion.actions.ts - Server actions for session CRUD operations

Voice Features:

• Microphone mute/unmute toggle
• Live speech-to-text transcription
• Soundwave visualization during speech
• Session duration tracking with live timer
• Automatic session history saving

Activity Heatmap:

• Weekly View - Bar chart with session counts
• Monthly View - Calendar grid with daily minutes
• Yearly View - GitHub-style contribution graph
• Export Functionality - Download as PNG/SVG

Streak Counter:

• Current streak tracking (consecutive days)
• Longest streak record
• "Active Today" indicator with fire emoji
• Last activity date display
• Real-time updates on session completion

Session History:

• Tabular view with companion name, subject, date, duration
• Export to CSV functionality
• Transcript viewer modal
• Sorting and filtering options

Multi-Step Form (CompanionForm.tsx):

1. Name - Companion display name
2. Subject - Select from 6 categories (Math, Science, Coding, etc.)
3. Topic - What should the companion teach? (Textarea)
4. Voice - Male or Female voice selection
5. Style - Formal or Casual teaching approach
6. Duration - Estimated session length (minutes)

Validation:

• Zod schema validation
• Real-time error messages
• Form state management via React Hook Form
• Loading animations during creation
• Success modal with auto-redirect

{
	id: UUID // Primary key
	name: string // Companion name
	subject: string // Subject category (maths, science, etc.)
	topic: string // Learning topic description
	voice: string // Voice preference (male/female)
	style: string // Teaching style (formal/casual)
	duration: number // Estimated session duration (minutes)
	author: string // User ID (Clerk)
	created_at: timestamp // Creation date
	updated_at: timestamp // Last update date
}

{
	id: UUID // Primary key
	companion_id: UUID // Foreign key → companions.id
	user_id: string // User ID (Clerk)
	duration_minutes: number // Actual session duration
	transcript: text // Full conversation transcript
	created_at: timestamp // Session start time
	completed_at: timestamp // Session end time
}

{
	id: UUID // Primary key
	companion_id: UUID // Foreign key → companions.id
	user_id: string // User ID (Clerk)
	created_at: timestamp // Bookmark date
	UNIQUE(companion_id, user_id) // One bookmark per user/companion
}

Science: #E5D0FF
(
Purple
)
Maths: #FFDA6E
(
Yellow
)
Language: #BDE7FF
(
Blue
)
Coding: #FFC8E4
(
Pink
)
History: #FFECC8
(
Beige
)
Economics: #C8FFDF
(
Green
)

• Backdrop Blur: backdrop-blur-lg
• Border: border border-white/20
• Background: bg-white/10
• Shadow: shadow-[0_8px_32px_0_rgba(31,38,135,0.37)]

• Font Family: Geist
• Headings: Bold, 2xl-4xl sizes
• Body Text: Regular, sm-lg sizes
• Code: Monospace for session timers

• Framer Motion: Page transitions, accordions, hover effects
• Lottie: Loading spinners, success checkmarks, empty states
• Custom Soundwaves: Real-time visualization during voice sessions

• Server-Side Caching - React Cache API for database queries
• Dynamic Imports - Code splitting for Lottie and heavy components
• Skeleton Loading - Perceived performance with loading states
• Image Optimization - Next.js Image component with lazy loading
• Turbopack - 700x faster than Webpack for local development

// Page revalidation times
export const revalidate = 180; // 3 minutes (companion detail pages)
export const revalidate = 300; // 5 minutes (my-journey page)

• Clerk Authentication - OAuth 2.0 with Google, GitHub, email
• Row-Level Security (RLS) - Supabase policies for data access
• Input Validation - Zod schemas for all form inputs
• CSRF Protection - Next.js built-in protection
• Environment Variables - Secrets stored in .env (gitignored)
• Sentry Monitoring - Real-time error tracking and alerting

User Login → Clerk OAuth → JWT Token → Supabase Client → RLS Policies → Data Access

• Free Users: 3 companions limit, 10 sessions/month
• Pro Users: Unlimited companions, unlimited sessions
• Admin: (Future) Companion moderation and analytics

Note: Most data operations use Server Actions (.actions.ts) instead of API routes for type safety and better performance.

// Companion CRUD
createCompanion(formData
:
CreateCompanion
):
Promise<Companion>
getAllCompanions(options
:
GetAllCompanions
):
Promise<Companion[]>
getCompanion(id
:
string
):
Promise<Companion>
// Session Management
addToSessionHistory(companionId
:
string
):
Promise<string>
updateSessionDuration(companionId
:
string, duration
:
number
):
Promise<void>
saveSessionTranscript(sessionId
:
string, transcript
:
string
):
Promise<void>
getRecentSessions(limit
:
number
):
Promise<Companion[]>
getUserSessions(userId
:
string, limit
:
number
):
Promise<Companion[]>
// Analytics
getHeatmapData(userId
:
string
):
Promise<HeatmapValue[]>
getWeeklyData(userId
:
string
):
Promise<WeeklyData[]>
getMonthlyData(userId
:
string
):
Promise<MonthlyData[]>
getUserStreakData(userId
:
string
):
Promise<StreakData>
// Bookmarks
toggleBookmark(companionId
:
string, isBookmarked
:
boolean, path
:
string
)
getBookmarkedCompanions(userId
:
string
):
Promise<Companion[]>

1. Push to GitHub

   git add .
   git commit -m "Initial commit"
   git push origin master

2. Connect to Vercel

   • Go to Vercel Dashboard
   • Import IntelliCourse-Next.js repository
   • Configure environment variables (copy from .env)
   • Deploy! 🎉

3. Post-Deployment

   • Update Clerk redirect URLs with production domain
   • Update VAPI webhook URLs (if applicable)
   • Configure Sentry DSN for production monitoring

# Development server with Turbopack
npm run dev
# Production build
npm run build
# Start production server
npm run start

Contributions are welcome! Please follow these guidelines:

1. Fork the repository 🍴
2. Create a feature branch (git checkout -b feature/amazing-feature) 🌟
3. Commit changes (git commit -m 'feat: Add amazing feature') 💾
4. Push to branch (git push origin feature/amazing-feature) 🚀
5. Open a Pull Request 📝

Follow Conventional Commits:

• feat: New feature
• fix: Bug fix
• docs: Documentation update
• style: Code style change (formatting)
• refactor: Code refactoring
• perf: Performance improvement
• test: Adding tests
• chore: Maintenance tasks

• Voice Session Stability: VAPI connection may drop on slow networks (~<1 Mbps)
• Safari Audio Issues: Microphone permissions require HTTPS in production
• Mobile Transcript View: Long transcripts may cause scroll performance issues

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

• Next.js Team - For the incredible React framework 🚀
• Vercel - For seamless hosting and deployment ☁️
• VAPI - For cutting-edge voice AI technology 🎙️
• Supabase - For the powerful open-source Firebase alternative 🗄️
• Clerk - For hassle-free authentication 🔐
• Tailwind Labs - For utility-first CSS framework 🎨
• Framer - For smooth animation library 🌊
• Sentry - For production monitoring and debugging 🐛
• Open Source Community - For endless inspiration and support 💙

If you found this project helpful or learned something new, please consider:

• ⭐ Starring this repository
• 🐛 Reporting bugs via Issues
• 💬 Sharing feedback and suggestions
• 🤝 Contributing to the codebase