๐Ÿš€ NeoCode - AI-Powered Learning Platform

Transform your coding journey with personalized AI mentorship, skill-based learning, and validated progress tracking.

React Node.js PostgreSQL Docker AI


๐Ÿ“– Table of Contents


๐ŸŒŸ Overview

NeoCode is not just another code judge - it's a comprehensive AI-powered learning platform that tracks your skills across all courses, provides personalized mentorship, validates your progress, and guides you toward your career goals.

What Makes NeoCode Different?

  • ๐Ÿง  AI Mentor System - Personalized coaching with memory of your entire learning journey
  • ๐ŸŽ™๏ธ Voice Interview System - Practice interviews with AI using natural voice conversation
  • Smart Review (Spaced Repetition) - Revisit weak concepts automatically based on interview performance
  • ๐Ÿ“Š Skill-Based Learning - Track skills across ALL courses (DSA from Course A + B = unified skill profile)
  • โœ… Validation Engine - No fake progress - prove you learned before leveling up
  • ๐ŸŽฏ Career Roadmaps - Set goals like "VR Engineer" and get AI-generated learning paths
  • ๐Ÿณ Docker Execution - Secure, isolated code execution in C++, Python, Java
  • ๐Ÿ“ˆ Cross-Course Analytics - See all your progress in one unified dashboard
  • ๐Ÿ”Œ Pluggable AI Providers - Use local models (Ollama, Whisper, Piper) or cloud (OpenAI, Gemini)

๐ŸŽฏ Key Features

๐Ÿ” Authentication & Authorization

  • JWT-based authentication with HTTP-only cookies
  • Role-based access control (Admin/User)
  • Secure password hashing with bcrypt

๐Ÿ’ป Code Execution Platform

  • Multi-language support: C++, Python, Java
  • Monaco Editor - VS Code-like coding experience
  • Docker containers - Secure, isolated execution
  • Container reuse - Optimized performance
  • Real-time test validation against hidden test cases
  • Save snippets for future reference

๐Ÿง  AI Mentor System (NEW!)

  • Personalized AI Mentor with full context of your learning
  • Skill Tracking across all courses and problems
  • Goal Management with career-focused roadmaps
  • Validation Engine requiring proof before skill level-ups
  • Daily Learning Plans generated by AI
  • Multi-modal Validation (Quiz + Code + Explain + Project)
  • Skill Dependency Graphs for structured learning

๏ฟฝ๏ธ Voice Interview System (NEW!)

Automated Setup: Run setup-voice-interview.ps1 for one-click installation to D:\models

  • ๐Ÿ—ฃ๏ธ Voice Interaction - Natural conversation with AI interviewer (speak & listen)
  • ๐Ÿ“š Topic-Based Interviews - Practice Arrays, DP, System Design, etc.
  • ๐Ÿ‘” Role-Based Interviews - Upload JD + resume for tailored questions
  • Coding Interview Problems - Full problem schema with hidden tests and combined code + speech evaluation
  • ๐Ÿ”Œ Pluggable Architecture - Swap STT/TTS/LLM providers without code changes
    • Whisper (OpenAI) for Speech-to-Text
    • Piper TTS for natural voice synthesis
    • Ollama (local) or OpenAI/Gemini for question generation
  • ๐Ÿ“Š Smart Evaluation - Real-time scoring with detailed feedback (0-100)
  • ๐Ÿ”— Learning OS Integration - Interview results feed into skill tracking
  • ๐Ÿ“ˆ Analytics Dashboard - Track performance across interview sessions
  • ๐Ÿ’พ All models stored locally in D:\models (~8-10 GB)

Quick Start: See voice interview setup below.

Voice Interview Setup:

# Full automatic installation (Whisper + Ollama + Piper)
powershell -ExecutionPolicy Bypass -File setup-voice-interview.ps1

# Custom installation path
powershell -ExecutionPolicy Bypass -File setup-voice-interview.ps1 -ModelsPath "C:\MyModels"

# Selective installation
powershell -ExecutionPolicy Bypass -File setup-voice-interview.ps1 -SkipWhisper

What Gets Installed:

  • Whisper (Speech-to-Text) - ~150MB
  • Ollama with llama2:13b - ~7.4GB
  • Piper TTS (Text-to-Speech) - ~50MB
  • Total: ~8-10 GB stored in D:\models

API Endpoints:

# Check system health
curl http://localhost:3000/api/interview/health

# Start interview
POST /api/interview/start
# Body: { session_mode, topic, difficulty, target_questions }

# Get next question (with audio)
POST /api/interview/:sessionId/question

# Submit audio answer
POST /api/interview/:sessionId/answer

# End session and get summary
POST /api/interview/:sessionId/end

# Get interview history
GET /api/interview/history

# Get performance analytics
GET /api/interview/analytics

Smart Review (Spaced Repetition) (NEW!)

  • Spaced repetition cards per concept (SM-2 simplified)
  • Due concept queue with max 10 per session
  • Gap-targeted Smart Review questions
  • Smart Review stats: due today, mastered, ease hell, streak

Smart Review API Endpoints:

GET  /api/interview/smart-review/due
POST /api/interview/smart-review/start
POST /api/interview/smart-review/complete
GET  /api/interview/smart-review/stats

๏ฟฝ๐ŸŽ“ Course Management

  • Complete course platform with problem assignments
  • Student enrollment and progress tracking
  • Course-specific submissions and analytics
  • Skill-based progression - Skills learned carry across courses
  • Points-based completion system
  • Paid course support with Stripe Checkout and SEPA Direct Debit
  • Course access gating: paid course content and course-only problems stay locked until enrollment is active
  • Course-only/hidden AI interview problems can be opened from paid courses after access is granted

๐Ÿ“Š Advanced Analytics

  • Unified Dashboard - See progress across ALL courses
  • Category points system with visual charts
  • Leaderboard system for healthy competition
  • Difficulty-based statistics
  • Real-time progress tracking
  • Weak/strong topic identification
  • Learning pattern analysis

๐Ÿค– AI-Powered Features

  • Multi-Provider LLM Integration (Ollama local + OpenAI + Gemini)
  • AI Code Review with actionable feedback
  • Complexity Analysis (Big O notation detection)
  • Smart Caching for AI responses
  • Interview Simulator with adaptive questions
  • AI Support Chat (restricted to logged-in users)
  • Mistake Pattern Detection

๐Ÿ“ Content Management

  • Rich blog system with Quill editor
  • Problem CRUD with category organization
  • Submission tracking and analytics
  • User management dashboard
  • Admin email console for sending manual Unosend messages to registered users

Payments & Email

  • Stripe Checkout integration for paid course purchases using SEPA Direct Debit
  • Stripe webhook processing for payment_intent.succeeded and SEPA async success events
  • Idempotent webhook tracking through stripe_webhook_events
  • Automatic course enrollment after successful payment
  • Unosend payment receipt emails after checkout confirmation
  • Email delivery audit trail through email_logs
  • Admin manual email sender at /admin/emails
  • Payment result pages at /payment/success and /payment/cancel

๐Ÿงพ Tech Stack

Frontend

  • React 18 with Vite
  • Tailwind CSS for styling
  • Framer Motion for animations
  • Monaco Editor for code editing
  • Chart.js for analytics
  • Axios for API calls
  • React Router for navigation

Backend

  • Node.js with Express.js
  • PostgreSQL database
  • JWT authentication
  • Docker for code execution
  • Multer for file uploads
  • Stripe for SEPA Direct Debit checkout
  • Unosend for transactional and admin emails

AI/LLM Integration

  • Local LLM (Ollama) for privacy
  • OpenAI API for advanced features
  • Google Gemini for complexity analysis
  • Pluggable architecture for multiple providers

DevOps

  • Docker containers for isolated execution
  • Container reuse for performance
  • PostgreSQL with migrations
  • Environment-based configuration
  • Stripe CLI for local webhook forwarding

๐Ÿ—๏ธ Architecture

System Overview

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                    FRONTEND (React)                         โ”‚
โ”‚  Landing โ†’ Dashboard โ†’ Problems โ†’ Courses โ†’ AI Chat         โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                     โ”‚ HTTP/REST API
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                  BACKEND (Node.js + Express)                โ”‚
โ”‚                                                              โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚
โ”‚  โ”‚   Routes     โ”‚โ†’ โ”‚  Controllers   โ”‚โ†’ โ”‚   Services     โ”‚ โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚
โ”‚                                                              โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚
โ”‚  โ”‚         AI MENTOR SYSTEM (Learning Core)            โ”‚  โ”‚
โ”‚  โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”     โ”‚  โ”‚
โ”‚  โ”‚  โ”‚ Skill Manager โ”‚  โ”‚ Goal Tracker           โ”‚     โ”‚  โ”‚
โ”‚  โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜     โ”‚  โ”‚
โ”‚  โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”     โ”‚  โ”‚
โ”‚  โ”‚  โ”‚ Validation    โ”‚  โ”‚ Roadmap Engine         โ”‚     โ”‚  โ”‚
โ”‚  โ”‚  โ”‚ Engine        โ”‚  โ”‚ (AI-powered)           โ”‚     โ”‚  โ”‚
โ”‚  โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜     โ”‚  โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
โ”‚                                                              โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚
โ”‚  โ”‚         LLM GATEWAY (Multi-Provider)                โ”‚  โ”‚
โ”‚  โ”‚  Ollama (Local) | OpenAI | Gemini                   โ”‚  โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                     โ”‚
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                  DATABASE (PostgreSQL)                       โ”‚
โ”‚                                                              โ”‚
โ”‚  Legacy: users, problems, courses, submissions               โ”‚
โ”‚  Learning OS: learning_profiles, training_plans              โ”‚
โ”‚  AI Mentor: user_skills, user_goals, validations (+9 more)  โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚           DOCKER CONTAINERS (Code Execution)                 โ”‚
โ”‚   cpp-container | python-container | java-container          โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

AI Mentor Architecture (6-Layer)

1. UI Layer         โ†’ User interface for dashboard, chat, goals
2. AI Mentor        โ†’ Strict coach persona with full context
3. Skill Engine     โ†’ Tracks user skills across all courses
4. Validation Layer โ†’ Prevents fake progress (quiz+code+project)
5. Memory Layer     โ†’ Stores learning history, patterns, goals
6. Course Integration โ†’ Maps course problems โ†’ skill updates

Data Flow: Problem Solved โ†’ Skill Updated

User solves problem in Course A
  โ†“
problem.execute.controller.js (verdict = ACCEPTED)
  โ†“
courseIntegration.onProblemSolved()
  โ†“
skillManagement.updateUserSkill()
  โ†“
user_skills table updated (confidence +5)
  โ†“
Dashboard shows unified skill progress across ALL courses

๐Ÿš€ Getting Started

Prerequisites

  • Node.js (v18+)
  • PostgreSQL (v14+)
  • Docker (for code execution)
  • Ollama (optional, for local LLM)

Installation

  1. Clone the repository

    git clone https://github.com/Rakesh-116/NeoCode-v2.git
    cd NeoCode-v2
    
  2. Install dependencies

    # Backend
    cd bz-server
    npm install
    
    # Frontend
    cd ../bz-client
    npm install
    
  3. Environment Setup

    Create .env in bz-server/:

    # Database
    DB_USER=postgres
    DB_PASSWORD=your_password
    DB_NAME=Neocode-v2
    DB_HOST=localhost
    DB_PORT=5432
    
    # JWT
    JWT_SECRET_KEY=your_super_secret_key_here
    
    # Server
    PORT=3000
    CLIENT_URL=http://localhost:5173
    SERVER_URL=http://localhost:3000
    
    # Stripe SEPA checkout
    STRIPE_SECRET_KEY=sk_test_your_key
    STRIPE_WEBHOOK_SECRET=whsec_your_cli_or_dashboard_secret
    
    # Unosend email
    UNOSEND_API_KEY=un_your_key
    UNOSEND_FROM=NeoCode <[email protected]>
    
    # AI Configuration
    LLM_PROVIDER=ollama  # or 'openai', 'gemini'
    OLLAMA_BASE_URL=http://localhost:11434
    OLLAMA_MODEL_NAME=llama3
    OPENAI_API_KEY=sk-...  # if using OpenAI
    GEMINI_API_KEY=...     # if using Gemini
    
    # AI Mentor Settings
    SKILL_CONFIDENCE_INCREMENT=5
    SKILL_LEVEL_UP_THRESHOLD=80
    VALIDATION_REQUIRED=true
    

    Create .env in bz-client/:

    VITE_BACKEND_URL=http://localhost:3000
    

    For Unosend, verify the sending domain before expecting emails to reach inboxes. Required DNS records usually include DKIM on unosend._domainkey, SPF on send, MX on send, and a recommended DMARC record such as:

    Type: TXT
    Name: _dmarc
    Content: v=DMARC1; p=none; rua=mailto:[email protected]
    
  4. Docker Setup for Code Execution

    Ensure Docker is installed and running on your system.

    Build Docker Images:

    cd bz-server/src/workers
    
    # Build containers for each language
    docker build -t cpp-comp ./cpp-worker
    docker build -t java-comp ./java-worker
    docker build -t python-comp ./python-worker
    

    Run Docker Containers:

    # Start containers (they will run in background)
    docker run -d --name cpp-container cpp-comp
    docker run -d --name java-container java-comp
    docker run -d --name python-container python-comp
    

    Verify Containers:

    # Check if containers are running
    docker ps
    

    You should see cpp-container, java-container, and python-container listed.

    Managing Containers:

    # Stop containers
    docker stop cpp-container java-container python-container
    
    # Remove containers
    docker rm cpp-container java-container python-container
    
    # Restart containers
    docker start cpp-container java-container python-container
    
  5. Run the application

    # Terminal 1 - Backend
    cd bz-server
    npm run dev
    
    # Terminal 2 - Frontend
    cd bz-client
    npm run dev
    

    For local Stripe webhook testing, install and log in to the Stripe CLI, then run:

    stripe listen --forward-to localhost:3000/api/webhooks/stripe
    

    Copy the printed whsec_... value into STRIPE_WEBHOOK_SECRET and restart the backend. Use Stripe test IBAN DE89370400440532013000 for SEPA checkout testing.

  6. Access the application


๐Ÿ—„๏ธ Database Setup

Create Database

psql -U postgres
CREATE DATABASE "Neocode-v2";
\q

Run Migrations

The AI Mentor System requires running database migrations in order:

cd bz-server

# Migration 1: Core AI Mentor tables (12 tables, 3 triggers, 2 views)
psql -U postgres -d Neocode-v2 -f database/migrations/002_ai_mentor_system.sql

# Migration 2: Skill catalog (15+ skills)
psql -U postgres -d Neocode-v2 -f database/migrations/003_seed_course_skill_mappings.sql

# Migration 11: Paid courses, Stripe payments, enrollments, and email logs
psql -U postgres -d Neocode-v2 -f src/database/migrations/011_course_payments.sql

Paid Course Payment Flow

Paid courses use a Stripe-hosted SEPA Direct Debit checkout. The frontend posts the selected courseId to /api/payments/checkout-session, the backend creates a Stripe Checkout Session, and the user is redirected to Stripe for IBAN entry and mandate consent.

After Stripe confirms the payment through the webhook:

  1. payments is updated to succeeded.
  2. course_enrollments is created or reactivated.
  3. Paid course hierarchy and course-only problems become accessible to that user.
  4. Unosend sends a payment receipt email.
  5. email_logs records whether the receipt or admin message was sent or failed.

The webhook route must be mounted before express.json() because Stripe signature verification requires the raw request body.

Email Deliverability Notes

NeoCode uses Unosend for both automatic payment receipts and manual admin emails. Unosend may show an email as Delivered once the recipient mail server accepts it, but mailbox placement can still be Inbox, Promotions, Spam, All Mail, or Trash depending on the recipient provider.

For local testing:

  • Verify the sender domain in Unosend before sending.
  • Use UNOSEND_FROM=NeoCode <[email protected]>.
  • Check email_logs for sent or failed rows.
  • Search Gmail with in:anywhere from:[email protected] if delivered mail is not visible.

Map Your Courses to Skills

After migrations, you need to connect your courses to skills:

  1. Find your course IDs:

    SELECT id, title FROM courses;
    
  2. Map courses to skills:

    -- Example: DSA Course
    INSERT INTO course_skills (course_id, skill_name, skill_weight, target_level, description)
    VALUES
      ('YOUR-COURSE-UUID', 'DSA', 10, 3, 'Core DSA proficiency'),
      ('YOUR-COURSE-UUID', 'Arrays', 8, 2, 'Array problem solving'),
      ('YOUR-COURSE-UUID', 'Trees', 9, 3, 'Tree algorithms');
    

See bz-server/database/migrations/HELPER_map_courses_to_skills.sql for detailed examples.

Database Schema

21 Total Tables:

  • 13 Legacy: users, problems, courses, submissions, blogs, etc.
  • 8 Learning OS: learning_profiles, training_plans, evaluations, etc.
  • 12 AI Mentor: user_skills, user_goals, validations, skill_catalog, roadmap_templates, etc.
  • Payments/Email: course_enrollments, payments, stripe_webhook_events, email_logs

Key Views:

  • skill_progress_across_courses - Aggregates skill data from all courses
  • problem_skill_mapping - Maps problem categories to skills

๐Ÿง  AI Mentor System

Philosophy

"Skills are universal. Courses are temporary paths. Your skill profile is your true progress."

The AI Mentor System tracks SKILLS, not courses. If you learn Arrays in Course A, that skill carries to Course B. Your dashboard shows unified skill levels across everything you've learned.

Core Features

1. Skill-Based Learning

  • Track 50+ skills (DSA, Arrays, Trees, VR, Unity, C#, etc.)
  • Skills aggregate across ALL courses
  • Level 0-5 progression with confidence tracking
  • Automatic updates when solving problems

2. Career Goals & Roadmaps

  • Set goals: "Become VR Engineer at Meta"
  • AI generates dependency-ordered roadmaps
  • Tracks required skills and progress
  • Recommends courses to fill skill gaps

3. Validation Engine (No Fake Progress)

  • Can't level up without proof
  • Multi-modal validation:
    • Quiz - Answer MCQs about concepts
    • Code - Write code from scratch
    • Explain - Explain solution approach
    • Project - Build real-world applications
  • Skill gates prevent advancement without validation

4. AI Mentor Chat

  • Strict coach persona (not casual chatbot)
  • Full context of your skills, goals, history
  • Blocks procrastination and excuses
  • Suggests next steps based on your trajectory

5. Daily Learning Plans

  • AI generates personalized daily tasks
  • Based on goals, weak topics, and schedule
  • Adaptive difficulty
  • Validation checkpoints

API Endpoints

# Skills
GET  /api/mentor/skills              # Get user skill profile
POST /api/mentor/skills/assessment   # Submit assessment
GET  /api/mentor/skills/gaps         # Identify skill gaps

# Goals
GET  /api/mentor/goals               # Get career goals
POST /api/mentor/goals               # Create goal
GET  /api/mentor/goals/:id           # Goal breakdown

# Validations
POST /api/mentor/validations         # Submit validation
GET  /api/mentor/validations/requirements/:skill/:level

# Roadmap
POST /api/mentor/roadmap/generate    # Generate AI roadmap
GET  /api/mentor/roadmap/active      # Get active roadmap
GET  /api/mentor/roadmap/tasks/today # Today's tasks

# Dashboard
GET  /api/mentor/dashboard           # Unified cross-course dashboard

# AI Chat
POST /api/mentor/chat                # Chat with mentor
GET  /api/mentor/chat/history        # Chat history

Dashboard Response

{
  "overview": {
    "courses_enrolled": 3,
    "problems_solved": 47,
    "skills_tracked": 12,
    "avg_confidence": 68,
    "validation_rate": 75
  },
  "skills": [
    {
      "skill_name": "Dynamic Programming",
      "level": 3,
      "confidence": 85,
      "learned_from_courses": ["dsa-striver", "algorithms-advanced"],
      "course_count": 2
    }
  ],
  "goals": [...],
  "todaysPlan": {...},
  "recommendations": {...}
}

๐Ÿ’ป Development

Project Structure

NeoCode-v2/
โ”œโ”€โ”€ bz-client/                 # Frontend React app
โ”‚   โ”œโ”€โ”€ src/
โ”‚   โ”‚   โ”œโ”€โ”€ components/
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ pages/         # Page components
โ”‚   โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ Home.jsx   # Landing page (NO gradients!)
โ”‚   โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ Footer.jsx # New footer design
โ”‚   โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ LearningProfile.jsx
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ Common/        # Reusable components
โ”‚   โ”‚   โ”œโ”€โ”€ context/           # React context
โ”‚   โ”‚   โ””โ”€โ”€ utils/             # Utilities
โ”‚   โ””โ”€โ”€ package.json
โ”‚
โ”œโ”€โ”€ bz-server/                 # Backend Node.js app
โ”‚   โ”œโ”€โ”€ src/
โ”‚   โ”‚   โ”œโ”€โ”€ controllers/       # Route controllers
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ mentor.controller.js        # AI Mentor endpoints
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ problem.execute.controller.js
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ courses.*.controller.js
โ”‚   โ”‚   โ”œโ”€โ”€ routes/            # API routes
โ”‚   โ”‚   โ”œโ”€โ”€ services/          # Business logic
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ courseIntegration.service.js  # Courseโ†’Skill sync
โ”‚   โ”‚   โ”œโ”€โ”€ learning-core/     # AI Mentor System
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ services/
โ”‚   โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ skillManagement.service.js
โ”‚   โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ goalTracking.service.js
โ”‚   โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ validationEngine.service.js
โ”‚   โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ enhancedRoadmap.service.js
โ”‚   โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ learningDashboard.service.js
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ routes/
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ controllers/
โ”‚   โ”‚   โ”œโ”€โ”€ ai/                # LLM integration
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ llmGateway.service.js  # Multi-provider
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ prompts/
โ”‚   โ”‚   โ”‚       โ””โ”€โ”€ mentor.prompt.js   # NeoMentor persona
โ”‚   โ”‚   โ”œโ”€โ”€ database/
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ connect.db.js
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ migrations/
โ”‚   โ”‚   โ”‚       โ”œโ”€โ”€ 002_ai_mentor_system.sql
โ”‚   โ”‚   โ”‚       โ””โ”€โ”€ 003_seed_course_skill_mappings.sql
โ”‚   โ”‚   โ””โ”€โ”€ workers/           # Docker execution
โ”‚   โ”‚       โ”œโ”€โ”€ cpp-worker/
โ”‚   โ”‚       โ”œโ”€โ”€ python-worker/
โ”‚   โ”‚       โ””โ”€โ”€ java-worker/
โ”‚   โ””โ”€โ”€ package.json
โ”‚
โ”œโ”€โ”€ NEOCODE_VISION.md          # Complete vision document
โ””โ”€โ”€ README.md                  # This file

Development Workflow

  1. Frontend Development

    cd bz-client
    npm run dev
    
- Changes auto-reload via Vite HMR
- Tailwind processes styles on-the-fly
  1. Backend Development

    cd bz-server
    npm run dev
    
- Nodemon auto-restarts on changes
- Watch logs for errors
  1. Database Changes

    • Create new migration file
    • Run with psql -U postgres -d Neocode-v2 -f migration.sql
    • Test thoroughly
  2. Adding AI Features

    • Update ai/prompts/ for new prompts
    • Modify llmGateway.service.js for provider changes
    • Use environment variables for API keys

Coding Standards

API & Configuration:

  • Use API URL (without URI) in config variables
  • Don't hardcode credentials - use environment variables
  • Support log levels (INFO, ERROR, DEBUG)
  • Never log sensitive information (passwords, keys, secrets)

Code Quality:

  • Brief, concise comments explaining what code does
  • Title comments at top of each file
  • Self-explanatory function names
  • Exception handling for all external connections
  • Assume every external call can fail
  • Use keepalive & timeouts for external API calls

Database:

  • Reduce DB calls through caching
  • Use table names in joins (e.g., problem.status, not just status)
  • Cache invalidation on data modification
  • Appropriate cache expiry times

Performance:

  • Prefer int over strings where possible (faster compare)
  • Strictly define function arguments (no optional params)
  • Define interfaces for object inputs (better engine performance)
  • Use imperative loops over functional loops (map, filter, reduce)
  • Use direct access instead of nested access in loops
  • Retrieve smallest amount of data possible
  • Iterate object values directly instead of fetching by key

API Responses:

  • Follow HTTP status code guidelines
  • Format JSON output properly (remove unnecessary fields)
  • Standardize error messages with function/class names

Client-Side:

  • Use session and local storage appropriately
  • No gradients in UI - use solid colors (bg-white/5, border-white/10)
  • Color palette: Black backgrounds, white text, white/60 for secondary

Testing

# Test problem submission
curl -X POST http://localhost:3000/api/problem/submit \
  -H "Authorization: Bearer YOUR_JWT" \
  -d '{"problemId":"...", "code":"...", "language":"python"}'

# Test dashboard
curl http://localhost:3000/api/mentor/dashboard \
  -H "Authorization: Bearer YOUR_JWT"

# Test skill update (solve any problem)
# Should see skill confidence increase

# Create a Stripe SEPA checkout session for a paid course
curl -X POST http://localhost:3000/api/payments/checkout-session \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"courseId":"COURSE_UUID"}'

# Send a manual admin email through Unosend
curl -X POST http://localhost:3000/api/admin/emails/send \
  -H "Authorization: Bearer ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{"userId":"USER_UUID","subject":"Hi","message":"Testing NeoCode email."}'

๐ŸŽฏ Roadmap

Phase 1: Core Platform โœ…

  • [x] Code execution (C++, Python, Java)
  • [x] Problem management
  • [x] Course system
  • [x] User authentication

Phase 2: Learning OS โœ…

  • [x] Learning profiles
  • [x] Training plans
  • [x] Mistake tracking
  • [x] Recommendations

Phase 3: AI Mentor System โœ…

  • [x] Skill tracking across courses
  • [x] Goal management
  • [x] Validation engine
  • [x] AI roadmap generation
  • [x] Daily learning plans
  • [x] Unified dashboard

Phase 4: Advanced Features (In Progress)

  • [x] Smart Review (spaced repetition for weak concepts)
  • [x] Coding interview problems with code + speech validation
  • [x] Paid course checkout with Stripe SEPA Direct Debit
  • [x] Paid course access gating and enrollment tracking
  • [x] Unosend payment receipt emails
  • [x] Admin manual email console
  • [x] Course-only hidden problem access for enrolled users

  • [ ] Skill assessments (auto-generated quizzes)

  • [ ] Project-based validations

  • [ ] Peer code review system

  • [ ] Career roadmap templates library

  • [ ] Skill dependency graph visualization

  • [ ] Learning analytics (time-to-mastery, retention)

Phase 5: Scale & Polish

  • [ ] Mobile app
  • [ ] Real-time collaboration
  • [ ] Video explanations
  • [ ] Community features
  • [ ] Gamification
  • [ ] Performance optimization

๐Ÿค Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

๐Ÿ“„ License

This project is licensed under the MIT License.


๐Ÿ‘จโ€๐Ÿ’ป Author

Rakesh Penugonda


๐Ÿ“š Documentation

For complete vision and philosophy, see NEOCODE_VISION.md


๐Ÿ™ Acknowledgments

  • Monaco Editor for the amazing code editor
  • Tailwind CSS for the utility-first styling
  • Docker for secure code execution
  • PostgreSQL for robust data storage
  • The open-source community for inspiration

Made with โค๏ธ and ๐Ÿ’ป by Rakesh Penugonda

Transform your coding journey with AI-powered mentorship! ๐Ÿš€

Built With

Share this project:

Updates