🎓 LearnPath AI — Prerequisite-Aware AI Learning Advisor

Personalized, Graph-Aware Learning Path Generator with Prerequisite Resolution & AI Guidance

🌐 Live Web App: https://learn-path-ai.netlify.app/  |  🐙 GitHub Repository: https://github.com/bikram73/LearnPath_AI

---

📑 Table of Contents

📖 Description	🚀 Section
View the project features and capabilities. 👉
View the technologies, frameworks, and programming languages used. 👉
Explore the project's folder and file organization. 👉
Follow the installation steps and local development setup. 👉
Understand the complete AI document processing pipeline. 👉
Learn about the AI prompting strategy and anti-hallucination techniques. 👉
Understand how confidence scores are calculated and interpreted. 👉
View all deliverables required for the AI challenge. 👉
View the available REST API endpoints and usage examples. 👉
Explore the complete system architecture, AI workflow, processing pipeline, data flow, deployment design, and technical decisions. 👉
Review implementation details, AI pipeline, performance metrics, benchmarking, validation strategy, privacy, testing, and technical specifications. 👉
Review processing speed, latency, and performance benchmarks. 👉
Understand the current limitations and known failure cases of the AI extractor. 👉

---

✨ Features

• 🎯 Intelligent Student Profile Wizard: 4-step wizard capturing academic background, current skills, desired career goal, experience level, weekly study hours, and learning style.
• 🌳 Prerequisite-Aware Topological Ordering: Builds a Directed Acyclic Graph (DAG) across courses ensuring foundational modules (e.g. Linear Algebra, Python, SQL) precede advanced subjects (e.g. Deep Learning, Distributed Systems).
• 🧩 Skill-Gap Analysis & Match Score: Evaluates user skills against target career profiles to identify acquired vs missing competencies with precision.
• 💬 Interactive AI Learning Advisor: Real-time context-aware chat assistant to discuss study pacing, course alternatives, capstone ideas, and career preparation.
• 📚 Comprehensive Course Catalog: Searchable and filterable course library with difficulty filters, duration tags, prerequisites, and key topic badges.
• 👥 Pre-configured Sample Personas: Instant one-click profiles representing common learner archetypes (e.g. Alex Rivera, Priya Patel, Marcus Chen).
• 📱 Adaptive Responsive UI & Mobile Navigation: Tailored desktop header + pinned mobile bottom navigation bar with fluid transitions.
• 🔒 Privacy-First Zero-Auth Architecture: Stateless computation with no tracking cookies or user login requirements.

---

🛠️ Tech Stack

💻 Languages & Runtimes

• TypeScript 5.8: Strongly typed frontend and backend code
• Node.js 20+: Backend runtime environment
• HTML5 & CSS3: Semantic markup and modern styling

🎨 Frontend Framework & Styling

• React 19: Modern component architecture with functional hooks
• Tailwind CSS v4: Utility-first styling engine with @tailwindcss/vite
• Lucide React: Modern iconography system
• Motion (Framer Motion): Smooth interactive UI transitions

⚙️ Backend & API Server

• Express.js 4.21: High-performance RESTful API endpoints
• Vite 6.2: Next-generation frontend build tool with middleware mounting in dev
• tsx: Ultra-fast TypeScript execution engine

🧠 Artificial Intelligence & Reasoning

• Google Gen AI SDK (@google/genai): Cascade architecture (gemini-2.5-flash / gemini-1.5-flash) for contextual rationale synthesis and conversational tutoring
• Deterministic Graph Engine: 3-color DFS topological sorting and prerequisite dependency resolution algorithm

---

📂 File Structure

learnpath-ai/
├── 📄 .env.example                 # Environment variables template
├── 📄 .gitignore                   # Git ignore configuration
├── 📄 index.html                   # HTML entry point with Inter font & SEO meta
├── 📄 metadata.json                # Project metadata & capabilities manifest
├── 📄 package.json                 # Project dependencies and npm scripts
├── 📄 server.ts                    # Express backend + Vite dev middleware server
├── 📄 tsconfig.json                # TypeScript compiler configuration
├── 📄 vite.config.ts               # Vite configuration with Tailwind CSS plugin
├── 📄 ARCHITECTURE.md              # Detailed architecture & workflow documentation
├── 📄 TECHNICAL_REPORT.md          # Technical specifications & benchmark report
├── 📄 TEST_PLAN.md                 # End-to-end testing & hardening plan
├── 📄 TEST_REPORT.md               # Measured test suite results matrix (63/63 PASS)
├── 📄 README.md                    # Main project documentation
│
├── 📁 tests/                       # Automated Verification & Hardening Suite
│   └── 📄 e2e-test-suite.ts        # Comprehensive E2E test runner (npm test)
│
└── 📁 src/                         # Application source code
    ├── 📄 App.tsx                  # Root React application layout & state routing
    ├── 📄 main.tsx                 # Client entry point
    ├── 📄 index.css                # Global Tailwind CSS imports & theme rules
    ├── 📄 types.ts                 # Central TypeScript interfaces & types
    │
    ├── 📁 components/              # Modular UI Components
    │   ├── 📄 Navbar.tsx           # Desktop top navigation header & brand identity
    │   ├── 📄 MobileBottomNav.tsx  # Pinned mobile bottom navigation bar
    │   ├── 📄 LandingPage.tsx      # Hero section, feature showcases, testimonials & FAQ
    │   ├── 📄 StudentProfileWizard.tsx # Multi-step interactive student questionnaire
    │   ├── 📄 RecommendationDashboard.tsx # Visual roadmap, milestone cards & AI chat
    │   ├── 📄 CourseCatalog.tsx    # Filterable catalog with search & prerequisite badges
    │   ├── 📄 SampleProfiles.tsx   # Ready-to-use learner profile personas
    │   ├── 📄 UserProfileModal.tsx # LocalStorage student profile management modal
    │   ├── 📄 AboutPage.tsx        # System architecture breakdown & methodology
    │   └── 📄 Footer.tsx           # Brand footer & navigation links
    │
    ├── 📁 data/                    # Local Datasets (Zero External DB)
    │   ├── 📄 courses.json         # Course catalog & prerequisite definitions
    │   ├── 📄 career_paths.json    # Target career competency matrices
    │   └── 📄 student_profiles.json # Pre-configured learner persona datasets
    │
    └── 📁 lib/                     # Algorithms & Shared Libraries
        ├── 📄 recommendationEngine.ts # DAG resolver, cycle detector & AI rationale layer
        └── 📄 storage.ts           # Browser LocalStorage synchronization helpers

---

🚀 Installation

1️⃣ Prerequisites

• Node.js: v18.0.0 or higher
• npm or bun / yarn / pnpm

2️⃣ Clone Repository & Install Dependencies

git clone https://github.com/bikram73/LearnPath_AI.git
cd LearnPath_AI
npm install

3️⃣ Set Up Environment Variables (Optional)

Create a .env file in the root directory:

cp .env.example .env

Add your optional AI API key if utilizing generative rationale generation:

GEMINI_API_KEY=your_api_key_here
PORT=3000

4️⃣ Start Development Server

npm run dev

Open your browser at http://localhost:3000 to explore LearnPath AI.

5️⃣ Build for Production

npm run build
npm start

---

🏗️ Architecture

┌────────────────────────────────────────────────────────┐
│                   User Interaction                     │
│         (Profile Wizard / Persona Selector / Search)   │
└──────────────────────────┬─────────────────────────────┘
                           │ POST /api/recommend
                           ▼
┌────────────────────────────────────────────────────────┐
│         Express REST API (`server.ts`)                 │
└──────────────────────────┬─────────────────────────────┘
                           │
             ┌─────────────┴─────────────┐
             ▼                           ▼
┌─────────────────────────┐ ┌─────────────────────────┐
│ Course Knowledge Graph  │ │  Skill Gap Resolution   │
│  (courses.json / DAG)   │ │   (Career Target Matrix)│
└────────────┬────────────┘ └────────────┬────────────┘
             │                           │
             └─────────────┬─────────────┘
                           │
                           ▼
┌────────────────────────────────────────────────────────┐
│  Topological Sort Engine (Prerequisite Resolver)       │
│  - Checks user acquired skills vs. course requirements │
│  - Enqueues required prerequisite courses strictly     │
│  - Ensures DAG validity & cycle-free ordering          │
└──────────────────────────┬─────────────────────────────┘
                           │
                           ▼
┌────────────────────────────────────────────────────────┐
│  AI Rationale Synthesis Layer (LLM Engine)             │
│  - Injects ordered courses + student profile context   │
│  - Generates custom benefits, milestones & timeline    │
│  - Fallback deterministic heuristic synthesis on error │
└──────────────────────────┬─────────────────────────────┘
                           │
                           ▼
┌────────────────────────────────────────────────────────┐
│  Recommendation Dashboard & Interactive Chat           │
│  - Visual Timeline Roadmap                             │
│  - Career Readiness Score & Match Breakdown            │
│  - Interactive AI Advisor Drawer                       │
└────────────────────────────────────────────────────────┘

---

🧠 Prompt Strategy

To eliminate hallucination and guarantee zero phantom course recommendations, LearnPath AI utilizes Strict Grounding & Constrained JSON Output:

1. Deterministic Catalog Injection: The AI model is strictly provided only the candidate courses resolved by the topological sorting engine. It is forbidden from inventing unlisted course IDs.
2. Schema Enforcement: Requests use responseMimeType: "application/json" with exact key bindings (aiSummary, careerOutcome, readinessScore, courseRationales).
3. Low Temperature Sampling: A temperature of 0.2 is configured to favor logical consistency and analytical precision over creative divergence.
4. Fallback Redundancy: If network latency or API rate limits occur, the system immediately switches to a built-in deterministic graph synthesizer without failing the user experience.

---

📊 Confidence & Readiness Metrics

The Career Readiness Score is calculated strictly via Deterministic Skill Coverage & Prerequisite Analysis:

$$\text{Career Readiness Score} = \text{clamp}\left(30, 96, \text{Baseline Skill Coverage} + \text{Roadmap Curriculum Boost}\right)$$

Where:

• Baseline Skill Coverage: $$\text{Baseline Coverage} = \left(\frac{|\text{Acquired Target Skills}|}{\max(1, |\text{Total Target Skills}|)}\right) \times 100$$

• Roadmap Curriculum Boost: $$\text{Roadmap Boost} = \min\left(45, \left(\frac{|\text{Ordered Courses}|}{\max(1, |\text{Candidate Courses}|)}\right) \times 40\right)$$

• Current Skill Coverage: The baseline percentage of prerequisites and target competencies the student currently possesses.

• Projected Skill Coverage After Roadmap: 100% (guaranteed prerequisite and skill gap closure upon completing all ordered sequence courses).

• Composite Readiness Metric: Calibrated purely deterministically from acquired prerequisite foundation plus roadmap curriculum coverage, completely eliminating arbitrary or non-deterministic AI score fluctuation.

---

📄 Challenge Deliverables

Deliverable	Status	Description
Interactive Profiling Wizard	✅ Complete	4-step wizard with real-time feedback & validation
Prerequisite Resolution Engine	✅ Complete	Graph topological sort respecting all course dependencies
Course Catalog Dataset	✅ Complete	Multi-disciplinary modules covering AI, Web, Cloud & Data
Visual Roadmap Dashboard	✅ Complete	Timeline milestones, skill badges, and progress tracking
AI Advisor Chat Assistant	✅ Complete	Real-time tutoring & roadmap adjustments
Responsive Mobile Experience	✅ Complete	Pinned bottom navigation & fluid mobile-first layouts

---

🌐 API Documentation

GET /api/courses

Returns all available courses in the catalog.

GET /api/profiles

Returns pre-populated sample learner personas.

POST /api/recommend

Generates a prerequisite-resolved learning path.

Request Body:

{
  "name": "Alex Rivera",
  "background": "Computer Science Student",
  "skills": ["Python", "Basic Git"],
  "goal": "AI Engineer",
  "experienceLevel": "Beginner",
  "weeklyHours": 12,
  "learningStyle": "Hands-on Projects"
}

POST /api/chat

Converses with the AI Learning Advisor.

Request Body:

{
  "message": "Which course should I focus on first?",
  "context": { "goal": "AI Engineer" }
}

---

⚡ Performance Benchmarks & Invariants

Benchmark Environment: Node.js 20+ / Vite 6.2 / TS 5.8
Test Suite Runs: 50 Iterations

Pipeline Step	Median Latency	P95 Latency	Notes
Deterministic DAG Sort	< 1.0 ms	< 2.5 ms	3-color DFS topological graph engine
Skill Gap Resolution	< 0.2 ms	< 0.5 ms	In-memory tokenized set intersection
AI Rationale Generation	~600 ms	~1200 ms	Google Gen AI SDK (@google/genai)
Deterministic Fallback	< 0.5 ms	< 1.0 ms	Instantaneous rule-based synthesizer
Client Bundle Size	< 180 KB	< 180 KB	Gzipped SPA bundle with Tailwind CSS v4

---

⚠️ Known Limitations

1. Fixed Catalog Scope: Recommendations are bound to courses defined within the local catalog dataset (courses.json).
2. Concurrent Multi-Goal Roadmaps: Currently optimizes for one primary target career path at a time.
3. Offline Mode: AI conversational chat requires active internet connectivity for generative insights (graph roadmap generation functions 100% offline).

---

_{Built with ❤️ for passionate learners worldwide • © 2026 LearnPath AI}