plan

AI-Powered Supplementary Learning Platform

Architecture Overview

graph TB subgraph frontend [Frontend - Next.js 15] AdminUI[Admin CMS UI] StudentUI[Student Browse UI] SearchUI[Search Interface] ChatUI[Chat Interface] GenUI[Content Generator UI] end

subgraph backend [Backend - API Routes]
    CMS[CMS API]
    Search[Search/RAG API]
    Generator[Content Generation API]
    Validator[Validation API]
    Chat[Chat API]
end

subgraph data [Data Layer]
    DB[(PostgreSQL)]
    VectorDB[Vector Embeddings]
    FileStorage[File Storage]
end

subgraph ai [AI Services]
    Gemini[Gemini API]
    Embeddings[Embedding Service]
    RAG[RAG Engine]
end

AdminUI --> CMS
StudentUI --> CMS
SearchUI --> Search
ChatUI --> Chat
GenUI --> Generator

CMS --> DB
CMS --> FileStorage
Search --> VectorDB
Search --> RAG
Generator --> Gemini
Generator --> Validator
Chat --> Search
Chat --> Generator
Chat --> Gemini

RAG --> VectorDB
RAG --> Gemini
Embeddings --> VectorDB

Database Schema

erDiagram User ||--o{ Course : teaches Course ||--o{ Material : contains Material ||--o{ Chunk : split_into Material ||--o{ GeneratedContent : generates User ||--o{ ChatSession : has ChatSession ||--o{ ChatMessage : contains

User {
    string id PK
    string email
    string name
    enum role
    timestamp created_at
}

Course {
    string id PK
    string name
    string description
    string user_id FK
    timestamp created_at
}

Material {
    string id PK
    string course_id FK
    enum type
    enum category
    string title
    string file_path
    json metadata
    timestamp created_at
}

Chunk {
    string id PK
    string material_id FK
    text content
    vector embedding
    json metadata
    int position
}

GeneratedContent {
    string id PK
    string material_id FK
    enum type
    text content
    json validation_results
    boolean is_validated
    timestamp created_at
}

ChatSession {
    string id PK
    string user_id FK
    string course_id FK
    timestamp created_at
}

ChatMessage {
    string id PK
    string session_id FK
    enum role
    text content
    json context
    timestamp created_at
}

Tech Stack

Frontend:

Next.js 15 (App Router)

TypeScript

Tailwind CSS + shadcn/ui components

React Server Components

Server Actions for mutations

Backend:

Next.js API Routes

Prisma ORM with PostgreSQL

pgvector extension for embeddings

AI/ML:

Gemini 3 Flash for generation & chat

Gemini embeddings for RAG

LangChain.js for RAG orchestration

File Storage:

Local filesystem (development)

AWS S3/Vercel Blob (production)

Additional:

PDF parsing: pdf-parse

Code parsing: @typescript-eslint/parser, esprima

Syntax validation: ESLint, Prettier

Implementation Plan

Phase 1: Project Setup & Database

Initialize Next.js Project:

npx create-next-app@latest . --typescript --tailwind --app

Install Dependencies:

npm install prisma @prisma/client @google/genai npm install langchain @langchain/google-genai npm install pdf-parse mammoth docx npm install react-markdown react-syntax-highlighter npm install @radix-ui/react-* class-variance-authority clsx tailwind-merge npm install zod react-hook-form @hookform/resolvers npm install -D @types/pdf-parse

Database Setup:

Create prisma/schema.prisma with schema above

Enable pgvector extension for vector embeddings

Models: User, Course, Material, Chunk, GeneratedContent, ChatSession, ChatMessage

Use Unsupported("vector") type for embedding columns

Environment Variables:

DATABASE_URL="postgresql://..." GEMINI_API_KEY="your_key"

Phase 2: Content Management System (CMS)

Admin Features:

File Upload API - app/api/materials/upload/route.ts

Handle multipart/form-data uploads

Support PDF, PPTX, DOCX, code files (.py, .js, .java, etc.)

Store in /uploads directory

Extract text content and metadata

Save to database with category (Theory/Lab)

Material Organization - app/api/materials/route.ts

CRUD operations for materials

Metadata: topic, week, tags, content_type

Category filter (Theory/Lab)

Admin UI - app/admin/materials/page.tsx

Upload form with drag-and-drop

Material list with filters

Metadata editing

Delete functionality

Student Features:

Browse Materials - app/materials/page.tsx

View all materials by category

Filter by week, tags, type

Download/view materials

Phase 3: Intelligent Search Engine (RAG)

Vector Embedding Pipeline:

Chunking Service - lib/chunking.ts

Split materials into semantic chunks (500-1000 tokens)

Preserve context (overlap 100 tokens)

For code: chunk by function/class

For PDFs: chunk by section/paragraph

Embedding Service - lib/embeddings.ts

Use Gemini embedding model

Generate embeddings for each chunk

Store in Chunk table with pgvector

Background Job - app/api/materials/process/route.ts

Trigger after upload

Parse content → chunk → embed → store

RAG Implementation:

Search API - app/api/search/route.ts

Accept natural language query

Generate query embedding

Cosine similarity search in pgvector

Return top-k relevant chunks (k=5-10)

Include source material metadata

Syntax-Aware Search - lib/code-search.ts

Parse code with AST

Index functions, classes, variables

Support queries like "authentication function" or "user model"

Search UI - app/search/page.tsx

Search bar with natural language input

Results display with context

Source material links

Code syntax highlighting

Phase 4: AI-Generated Learning Materials

Theory Generation:

Generator Service - lib/generators/theory.ts

Input: topic/concept + user prompt

RAG: Retrieve relevant course chunks

Gemini prompt: Generate reading notes based on context

Output formats: Markdown, PDF (react-pdf)

API Endpoint - app/api/generate/theory/route.ts

Accept topic and format preference

Call RAG for context

Stream Gemini response

Return generated content

Lab/Code Generation:

Code Generator - lib/generators/lab.ts

Input: topic + language

RAG: Find similar code examples

Gemini prompt: Generate syntactically correct code

Support: Python, JavaScript, Java, C++

API Endpoint - app/api/generate/lab/route.ts

Accept topic and language

Retrieve code examples via RAG

Generate with Gemini

Return code with explanation

UI:

Generator Interface - app/generate/page.tsx

Topic input with autocomplete

Type selector (Theory/Lab)

Format/language selector

Real-time generation display

Save to materials option

Phase 5: Content Validation & Evaluation

Code Validation:

Syntax Validator - lib/validators/code.ts

Parse with language-specific parsers

ESLint for JS/TS

Python AST for Python

Return syntax errors with line numbers

Compilation Check - lib/validators/compile.ts

TypeScript: run tsc in sandbox

Python: compile() function

Capture errors

Theory Validation:

Grounding Check - lib/validators/grounding.ts

Extract key claims from generated content

RAG search for supporting evidence

Flag unsupported claims

AI Self-Evaluation - lib/validators/ai-eval.ts

Prompt Gemini to evaluate its own output

Rubric: correctness, relevance, completeness

Return scores and explanations

API:

Validation Endpoint - app/api/validate/route.ts

Accept generated content

Run all applicable validators

Store validation results

Return pass/fail with details

Phase 6: Conversational Chat Interface

Chat Backend:

Chat Service - lib/chat/service.ts

Maintain conversation context

Tool/function calling for features:

search_materials(query) → Part 2

generate_content(topic, type) → Part 3

explain_material(material_id) → RAG

Gemini with function calling

Chat API - app/api/chat/route.ts

POST new message

GET session history

Streaming responses

Context management (last 10 messages)

Chat UI:

Chat Interface - app/chat/page.tsx

Message list with role indicators

Input with file attachment support

Streaming message display

Quick actions (search, generate)

Session persistence

Integration - Add chat widget to all pages

Floating chat button

Slide-in panel

Context-aware (current page)

Phase 7: Authentication & Authorization

Auth Setup - Use NextAuth.js or Clerk

Admin vs Student roles

Course enrollment

Session management

Protected Routes - middleware.ts

Admin-only: CMS, upload

Student: browse, search, chat, generate

Phase 8: UI/UX Polish

Design System - Use shadcn/ui components

Consistent styling

Dark mode support

Responsive design

Loading States - Skeletons, spinners

Error Handling - Toast notifications, error boundaries

Accessibility - ARIA labels, keyboard navigation

Bonus Features (Optional)

1. Handwritten Notes Digitization:

Use Gemini Vision API

Upload image → OCR → LaTeX/Markdown

Endpoint: app/api/digitize/route.ts

2. Content-to-Video Generation:

Use Veo 3.1 API (from geminiAPi reference)

Generate video summaries from notes

Endpoint: app/api/generate/video/route.ts

3. Community Forum + Bot:

Simple forum with posts/replies

Bot monitoring with Gemini

Auto-reply when user unavailable

Schema: Post, Reply, BotResponse

Key Files to Create

Configuration:

prisma/schema.prisma - Database models

.env - Environment variables

next.config.js - Next.js config

tailwind.config.ts - Tailwind config

Database:

lib/db.ts - Prisma client singleton

AI Services:

lib/gemini.ts - Gemini client setup

lib/embeddings.ts - Embedding generation

lib/rag.ts - RAG orchestration

lib/chunking.ts - Content chunking

API Routes:

app/api/materials/route.ts - Material CRUD

app/api/materials/upload/route.ts - File upload

app/api/search/route.ts - Semantic search

app/api/generate/theory/route.ts - Theory generation

app/api/generate/lab/route.ts - Code generation

app/api/validate/route.ts - Validation

app/api/chat/route.ts - Chat interface

Pages:

app/page.tsx - Landing page

app/admin/materials/page.tsx - Admin CMS

app/materials/page.tsx - Browse materials

app/search/page.tsx - Search interface

app/generate/page.tsx - Content generator

app/chat/page.tsx - Chat interface

Validators:

lib/validators/code.ts - Syntax checking

lib/validators/grounding.ts - Fact verification

lib/validators/ai-eval.ts - AI self-evaluation

Utilities:

lib/parsers/pdf.ts - PDF parsing

lib/parsers/docx.ts - DOCX parsing

lib/parsers/code.ts - Code parsing

lib/utils/file-upload.ts - File handling

Testing Strategy

Unit Tests - Jest for utilities, parsers, validators

Integration Tests - Test API endpoints

E2E Tests - Playwright for critical flows

Manual Testing - Search quality, generation accuracy

Deployment Considerations

Database - PostgreSQL with pgvector (Neon, Supabase)

File Storage - Vercel Blob or AWS S3

Hosting - Vercel for Next.js

Environment - Manage API keys securely

Rate Limiting - Protect Gemini API calls

Success Metrics

Upload and organize 50+ materials across Theory/Lab

Search returns relevant results in <2s

Generated content passes validation >80%

Chat responds contextually in <3s

Clean, intuitive UI with <3 clicks to any feature