AI Study Tutor - Technical Documentation

# 1. Clone the repository
git clone <repo-url>
cd AI-Study-Tutor

# 2. Frontend (cognify-frontend)
cd cognify-frontend && npm install && npm run dev
# Runs on http://localhost:5173

# 3. Node.js Backend (node-backend)
cd ../node-backend && npm install
cp .env.example .env  # Configure your .env
npm run dev
# Runs on http://localhost:4000

# 4. FastAPI Backend (ai-engine)
cd ../ai-engine

# Create virtual environment
python -m venv venv
source venv/bin/activate  # macOS/Linux
# Windows: venv\Scripts\activate

# Install and run
pip install -r requirements.txt
cp .env.example .env  # Configure your .env
uvicorn app.main:app --reload
# Runs on http://localhost:8000

# Example connection string:
mongodb+srv://username:password@cluster0.xxxxx.mongodb.net/rag_app

# Add to node-backend/.env:
MONGO_URI=mongodb+srv://username:password@cluster0.xxxxx.mongodb.net/rag_app

MONGO_URI=mongodb+srv://...
JWT_SECRET=your-secret
GOOGLE_CLIENT_ID=xxx
EMAIL_USER=email@zoho.in
EMAIL_PASSWORD=xxx

LLM_PROVIDER=gemini
GOOGLE_API_KEY=your-key
JWT_SECRET=your-secret

1. Technology Stack

1.1 Frontend (cognify-frontend)

Why these choices?

• React 19: Latest React with improved performance and concurrent features
• Vite: 10x faster than Webpack for development builds
• TailwindCSS 4: Rapid UI development with atomic CSS classes
• Redux Toolkit: Simplified Redux with built-in best practices and persistence for offline-first architecture

1.2 Node.js Backend (node-backend)

Why these choices?

• Express.js: Lightweight, battle-tested, with massive ecosystem
• MongoDB: Flexible document storage for varying workspace/document structures
• JWT: Stateless auth eliminates session storage, scales horizontally
• Multer: Industry standard for multipart/form-data handling

1.3 FastAPI Backend (ai-engine)

Why these choices?

• FastAPI: Native async/await, automatic OpenAPI docs, type validation
• ChromaDB: Lightweight, embedded vector DB - no external service needed
• Sentence Transformers: High-quality embeddings with all-MiniLM-L6-v2 model
• Multi-LLM Factory: Flexibility to switch between providers (cost/performance optimization)

2. Storage Configuration

The application supports dual storage providers with a unified abstraction layer:

2.1 Storage Provider Architecture

2.2 Local Storage Provider

Configuration:

STORAGE_PROVIDER=local
LOCAL_STORAGE_PATH=../application-data

How it works:

1. Files stored in application-data/ folder at project root
2. Node.js serves as static file server via Express
3. URLs return as {BACKEND_URL}/storage/{key}
4. Path traversal protection with key sanitization

File organization:

application-data/
└── {userEmail}/
    └── workspaces/
        └── {workspaceId}/
            ├── pdfs/
            │   └── {timestamp}-{filename}.pdf
            └── texts/
                └── {timestamp}-{title}.txt

2.3 AWS S3 Storage Provider

Configuration:

STORAGE_PROVIDER=s3
AWS_S3_BUCKET=your-bucket-name
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key

How it works:

1. Files uploaded to S3 bucket with structured keys
2. Pre-signed URLs generated for secure, time-limited access
3. Supports CloudFront CDN for global distribution
4. Same file organization pattern as local storage

S3 URL format:

https://{bucket}.s3.{region}.amazonaws.com/{key}

2.4 Switching Between Providers

Simply change the STORAGE_PROVIDER environment variable:

Both backends (Node.js and FastAPI) use the same abstraction, ensuring consistent file access across the stack.

3. Technical Flow & Architecture

3.1 High-Level Architecture

3.2 Complete Workflow

Step 1: User Authentication (Node.js)

Step 2: Document Upload Flow

Step 3: RAG Chat Flow

Step 4: Content Generation Flow

3.3 LLM Provider (Simple .env Switch)

Switching LLM providers requires only updating 2 environment variables in ai-engine/.env:

# Just change these two lines to switch providers:
LLM_PROVIDER=gemini          # Options: gemini, openai, deepinfra, ollama, bedrock
GOOGLE_API_KEY=your-api-key  # Add the corresponding API key

Available Providers:

Example Configurations:

# Use Google Gemini (default)
LLM_PROVIDER=gemini
GOOGLE_API_KEY=AIzaSy...

# Use OpenAI
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...

# Use local Ollama (no API key needed)
LLM_PROVIDER=ollama
OLLAMA_HOST=http://localhost:11434

3.4 Vector Store (ChromaDB)

Configuration:

CHROMA_PERSIST_DIR=./chroma_db
EMBEDDING_MODEL=all-MiniLM-L6-v2
CHUNK_SIZE=500
CHUNK_OVERLAP=100

Key Operations:

Semantic Chunking Strategy:

1. Split on paragraph boundaries (\n\n)
2. Further split large paragraphs at sentence boundaries
3. Merge tiny chunks (< 100 chars) with neighbors
4. Include parent window indices for context expansion

4. API Endpoints Summary

Node.js Backend (localhost:4000)

FastAPI Backend (localhost:8000)

5. Environment Variables Reference

Node.js Backend (.env)

# Server
NODE_ENV=development
PORT=4000
CORS_ORIGINS=http://localhost:5173

# Database
MONGODB_URI=mongodb://localhost:27017/rag_app

# JWT (shared with FastAPI)
JWT_SECRET=your-super-secret-key
JWT_EXPIRES_IN=7d

# Storage
STORAGE_PROVIDER=local
LOCAL_STORAGE_PATH=../application-data
AWS_S3_BUCKET=your-bucket
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=xxx
AWS_SECRET_ACCESS_KEY=xxx

# OAuth
GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com

FastAPI Backend (.env)

# LLM
LLM_PROVIDER=gemini
GOOGLE_API_KEY=your-api-key
DEEPINFRA_API_KEY=xxx
OPENAI_API_KEY=xxx

# Vector Store
CHROMA_PERSIST_DIR=./chroma_db
EMBEDDING_MODEL=all-MiniLM-L6-v2

# Storage (same as Node.js)
STORAGE_PROVIDER=local
LOCAL_STORAGE_PATH=../application-data

# JWT (shared)
JWT_SECRET=your-super-secret-key

6. Advanced Retrieval Engine

The RAG system uses a sophisticated multi-stage retrieval pipeline for significantly improved accuracy:

6.1 Retrieval Architecture

6.2 Retrieval Techniques

6.3 Re-Ranking Model

The system uses cross-encoder/ms-marco-MiniLM-L-6-v2:

• Trained on MS MARCO passage ranking dataset
• Takes (query, document) pairs and outputs relevance score
• Significantly improves top-k precision over raw vector search

7. Error Handling

7.1 FastAPI Error Handling

# Graceful LLM failure handling
try:
    response = await self.llm.generate(messages)
    return response.content
except Exception as e:
    print(f"[RAGAgent] Error: {e}")
    return "I encountered an error. Please try again."

7.2 JSON Repair for LLM Outputs

The DeepContentGenerator includes robust JSON parsing:

• Extracts JSON from markdown code blocks
• Repairs truncated strings and arrays
• Handles unbalanced brackets
• Fallback to default structures on failure

7.3 Storage Fallbacks

// Node.js: Graceful storage errors
async getFileBuffer(key: string): Promise<Buffer> {
  try {
    return await readFile(this.getFullPath(key));
  } catch (error) {
    logger.error(`Failed to read file: ${key}`, error);
    throw new NotFoundError(`File not found: ${key}`);
  }
}

8. Email Service (Nodemailer)

The application uses Nodemailer for sending OTP verification emails during user registration.

8.1 Environment Variables

Add these to your node-backend/.env file:

# Email Configuration (Zoho Mail - Default)
EMAIL_USER=your-email@zoho.in
EMAIL_PASSWORD=your-zoho-app-password

8.2 SMTP Configuration

Default Setup (Zoho Mail India):

// services/emailService.ts
const transporter = nodemailer.createTransport({
  host: "smtp.zoho.in",       // Zoho India SMTP server
  port: 465,                   // SSL port
  secure: true,                // Use TLS encryption
  auth: {
    user: config.emailUser,    // EMAIL_USER from .env
    pass: config.emailPassword // EMAIL_PASSWORD from .env
  },
});

8.3 Alternative Email Providers

To switch providers, modify emailService.ts:

Gmail:

const transporter = nodemailer.createTransport({
  host: "smtp.gmail.com",
  port: 587,
  secure: false,
  auth: {
    user: config.emailUser,
    pass: config.emailPassword, // Use App Password (not regular password)
  },
});

SendGrid (Recommended for Production):

const transporter = nodemailer.createTransport({
  host: "smtp.sendgrid.net",
  port: 587,
  auth: {
    user: "apikey",
    pass: process.env.SENDGRID_API_KEY,
  },
});

8.4 Email Features

8.5 Getting Zoho Credentials

1. Create a Zoho Mail account at mail.zoho.in
2. Go to Settings → Security → App Passwords
3. Click Generate New Password
4. Select "Other Apps" as the application
5. Copy the generated 16-character password
6. Use your Zoho email as EMAIL_USER
7. Use the App Password as EMAIL_PASSWORD

8.6 Email Template Preview

The OTP email includes:

• Dark gradient theme matching the app design
• Prominent OTP display with letter spacing
• 10-minute expiry notice
• Brand footer with copyright

8.7 Troubleshooting