Transform your PDF documents into interactive study materials with AI-powered tools!

• Overview
• Features
• Tech Stack
• Prerequisites
• Installation
• Configuration
• Usage
• API Documentation
• Project Structure
• Contributing
• License

SubRevision is an intelligent study companion that leverages AI to help students learn more effectively. Upload any PDF document and instantly generate:

• ❓ Q&A System - Ask questions and get context-aware answers
• 🔍 Smart Search - Find relevant content quickly
• 📝 Auto Summaries - Get comprehensive document summaries
• 🎯 Interactive Quizzes - Test your knowledge with auto-generated questions
• 🃏 3D Flashcards - Flip-to-learn with beautiful card animations
• 🧠 Mind Maps - Visualize concepts hierarchically
• 📅 Study Plans - Get personalized day-by-day study schedules

• 🎮 Pixel Art Theme - Retro-inspired, midnight study aesthetic
• 🌙 Dark Mode - Easy on the eyes for late-night studying
• 📱 Responsive Design - Works on desktop, tablet, and mobile
• ⚡ Real-time Loading States - Visual feedback for all operations
• 🎭 Interactive Components - Click-to-reveal answers, flip cards
• 🎨 Color-coded Content - Different colors for different content types

• FastAPI - High-performance Python web framework
• Groq API - Ultra-fast AI inference with Llama 3.3 70B
• PyPDF2 - PDF text extraction
• Python 3.12 - Modern Python runtime
• Uvicorn - ASGI server for production

• Next.js 16 - React framework with App Router
• React 19 - Latest React with concurrent features
• TypeScript 5 - Type-safe JavaScript
• Tailwind CSS 4 - Utility-first CSS framework
• Turbopack - Next-gen bundler (dev mode)

• Groq Cloud - Free AI API with 30 req/min, 14,400 req/day
• Llama 3.3 70B Versatile - State-of-the-art LLM
• JSON Vector Storage - Lightweight document storage

Before you begin, ensure you have:

• Python 3.12+ (Download)
• Node.js 20+ & npm (Download)
• Git (Download)
• Groq API Key (Free at console.groq.com)

git clone https://github.com/muskiteer/SubRevision.git
cd SubRevision

# Navigate to backend directory
cd backend

# Create virtual environment
python3 -m venv .venv

# Activate virtual environment
# On Linux/Mac:
source .venv/bin/activate
# On Windows:
# .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Navigate to frontend directory (from project root)
cd frontend

# Install dependencies
npm install

Create a .env file in the backend/ directory:

cd backend
touch .env

Add your Groq API key:

GROQ_API_KEY=your_groq_api_key_here

Get Your Free Groq API Key:

1. Visit console.groq.com
2. Sign up/Login
3. Navigate to API Keys
4. Create new key
5. Copy and paste into .env

The frontend is pre-configured to connect to http://localhost:8000 (backend).

If you need to change the API URL, edit frontend/app/page.tsx:

const API_BASE = 'http://localhost:8000'; // Change if needed

Terminal 1 - Backend:

cd backend
source .venv/bin/activate  # Activate virtual environment
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Terminal 2 - Frontend:

cd frontend
npm run dev

# Start backend in background
cd backend && source .venv/bin/activate && uvicorn main:app --reload &

# Start frontend in background
cd frontend && npm run dev &

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs (Swagger UI)
• Alternative API Docs: http://localhost:8000/redoc (ReDoc)

Full API Documentation: Visit http://localhost:8000/docs for interactive Swagger UI.

SubRevision/
├── backend/                    # Python FastAPI backend
│   ├── db/                     # Database layer
│   │   ├── db.py              # Vector storage implementation
│   │   └── __init__.py
│   ├── handlers/              # Business logic
│   │   ├── handler.py         # API request handlers
│   │   └── __init__.py
│   ├── routes/                # API routes
│   │   ├── routes.py          # Endpoint definitions
│   │   └── __init__.py
│   ├── utils/                 # Utility functions
│   │   ├── pdf_processor.py  # PDF extraction logic
│   │   └── __init__.py
│   ├── main.py                # FastAPI application entry
│   ├── requirements.txt       # Python dependencies
│   ├── .env                   # Environment variables (create this)
│   └── GROQ_SETUP.md         # Groq API setup guide
│
├── frontend/                  # Next.js frontend
│   ├── app/                   # Next.js App Router
│   │   ├── layout.tsx        # Root layout
│   │   ├── page.tsx          # Main page component
│   │   └── globals.css       # Global styles (pixel theme)
│   ├── public/               # Static assets
│   ├── package.json          # Node dependencies
│   ├── tsconfig.json         # TypeScript config
│   ├── next.config.ts        # Next.js config
│   ├── tailwind.config.ts    # Tailwind config
│   └── postcss.config.mjs    # PostCSS config
│
└── README.md                  # This file

8 tabs for different features:

• 📄 Upload PDF
• ❓ Ask Query
• 🔍 Search
• 📝 Summary
• 🎯 Quiz
• 🃏 Flashcards
• 🧠 Mind Map
• 📅 Study Plan

Quiz Questions:

• Click "Show Answer" to reveal
• Color-coded: Question (cyan) → Answer (green)
• Smooth fade-in animations

Flashcards:

• 3D flip animation on click
• Front: Cyan border (question)
• Back: Green border (answer)
• Responsive grid layout

Mind Map:

• Hierarchical tree structure
• Color-coded by depth level
• Expandable/collapsible nodes

Study Plan:

• Day-by-day cards
• Topics with cyan bullets
• Tasks with yellow checkboxes
• Duration indicators

# Backend tests (if available)
cd backend
pytest

# Frontend tests (if available)
cd frontend
npm test

Backend:

cd backend
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8000

Frontend:

cd frontend
npm run build
npm start

Create Dockerfile in backend:

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Create Dockerfile in frontend:

FROM node:20-alpine
WORKDIR /app
COPY package*.json .
RUN npm install
COPY . .
RUN npm run build
CMD ["npm", "start"]

1. "No PDF uploaded yet" error

• Make sure to upload a PDF before using other features
• Check if upload was successful (status message)

2. Backend connection refused

• Verify backend is running on port 8000
• Check CORS settings in backend/main.py
• Ensure firewall allows port 8000

3. Groq API errors

• Verify API key in .env file
• Check API quota (30 req/min, 14,400 req/day)
• Ensure no extra spaces in API key

4. Frontend not connecting to backend

• Check API_BASE URL in frontend/app/page.tsx
• Verify backend is accessible at that URL
• Check browser console for CORS errors

5. PDF upload fails

• Ensure file is under 50MB
• Check file is valid PDF format
• Verify backend has write permissions

• Rate Limit: 30 requests/minute
• Daily Limit: 14,400 requests/day
• Model: llama-3.3-70b-versatile
• Speed: ~1000 tokens/second
• Cost: FREE ✨

• Handles PDFs up to 50MB
• Chunks text into 500-char segments
• Stores vectors in JSON (lightweight)
• CORS enabled for localhost:3000

• Next.js 16 with Turbopack (dev)
• React 19 concurrent rendering
• Client-side state management
• No external API calls except backend

We welcome contributions! Here's how:

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

• Follow PEP 8 for Python code
• Use ESLint/Prettier for TypeScript
• Add comments for complex logic
• Update README for new features
• Test before submitting PR

• Groq for providing free, ultra-fast AI inference
• Meta for the Llama 3.3 model
• FastAPI for the excellent Python framework
• Vercel for Next.js and amazing developer experience
• Tailwind CSS for the utility-first CSS framework