🎓 ExamAI

ExamAI is a state-of-the-art, AI-powered competitive exam preparation platform designed specifically for students tackling high-stakes engineering exams: JEE Mains, JEE Advanced, GATE, and EAMCET.

By leveraging advanced Gemini models, ExamAI offers an interactive tutoring assistant, dynamic mock test generation, instant question solvers via PDF/Image uploads, similarity-based practice generation, and deep performance diagnostics.

🏗️ System Architecture

ExamAI splits core logic between a responsive Next.js frontend and an AI-orchestrated Flask backend. The diagram below illustrates how components interact:

graph LR
    %% Styling Definitions
    classDef frontend fill:#eef2ff,stroke:#6366f1,stroke-width:2px,color:#1e1b4b;
    classDef backend fill:#f0fdf4,stroke:#22c55e,stroke-width:2px,color:#14532d;
    classDef ai fill:#faf5ff,stroke:#a855f7,stroke-width:2px,color:#3b0764;
    classDef component fill:#ffffff,stroke:#94a3b8,stroke-dasharray: 4 4,color:#334155;

    subgraph Frontend ["🖥️ FRONTEND (Next.js & React)"]
        UI("User Interface <br> (Dashboard / Chat / Test)"):::frontend
        Charts(["Performance Charts <br> (Recharts)"]):::component
        Math(["Math Formulator <br> (KaTeX)"]):::component
        
        UI --> Math
        UI --> Charts
    end

    subgraph Backend ["⚙️ BACKEND (Flask REST API)"]
        Router("API Blueprint <br> Router"):::backend
        PDF["PDF Text Extractor <br> (pdfplumber)"]:::component
        Img["Image Processor <br> (Pillow)"]:::component
        Env[("Config Loader <br> (.env.local)")]:::component
        
        Router --> Env
        Router --> PDF
        Router --> Img
    end

    subgraph AI ["🧠 AI ENGINE (Google Gemini)"]
        Gemini{"Gemini API <br> (3.1-flash-lite)"}:::ai
    end

    %% Apply Subgraph Styles for Light Mode Aesthetics
    style Frontend fill:#f8fafc,stroke:#cbd5e1,stroke-width:2px,color:#0f172a;
    style Backend fill:#f8fafc,stroke:#cbd5e1,stroke-width:2px,color:#0f172a;
    style AI fill:#f8fafc,stroke:#cbd5e1,stroke-width:2px,color:#0f172a;

    %% Horizontal connections
    UI ==>|"1. REST / SSE Requests"| Router
    Router ==>|"2. Structured Prompts"| Gemini
    Gemini ==>|"3. JSON / SSE Chunks"| Router
    Router ==>|"4. Evaluated Answers"| UI

✨ Core Features

💬 1. Interactive AI Tutor (Chat)

Exam-Specific Personas: Adapts system instructions based on the selected exam (JEE Mains, Advanced, GATE, EAMCET) to customize concept depth and hints.
Low-Latency Streaming: Utilizes Server-Sent Events (SSE) stream responses for real-time text delivery.
LaTeX Math Rendering: Displays scientific math formulas and equations inline or in display blocks using KaTeX.

📝 2. Dynamic Mock Test Generator

Tailored Tests: Creates customized test papers targeting specific subjects, difficulty levels, and question counts.
JSON-Structured Output: Integrates Gemini's Structured Output Mode to serve valid, parsed JSON containing multiple-choice options, correct keys, and explanations.

🔬 3. Auto-Evaluation & Performance Diagnostics

Syllabus Scoring: Automatically calculates scores according to standard marking schemes (e.g., JEE: +4/-1; GATE: +1/-0.33; EAMCET: +1/0).
Weakness Diagnosis: Feeds incorrectly answered questions back to the Gemini model to identify the top 3 specific weak concepts (e.g., Electrostatics, Integration, Kinematics).

📤 4. PDF & Image Question Solver

Multi-Modal Solving: Parses PDF assignments via pdfplumber or images (PNG, JPEG, WebP) via Gemini Vision API.
Step-by-Step Walkthroughs: Provides explanations including concept breakdown, core formulas, and exam tips.

🔄 5. Similar Question Generator

Concept Re-enforcement: Generates 3 customized variants of any selected question with adjusted parameters/values, letting students practice the same concept until mastery.

🛠️ Tech Stack

Layer	Technology	Primary Purpose
Frontend	Next.js 16 (App Router)	Framework & routing architecture
	React 19	Component-driven UI rendering
	Tailwind CSS v4	Modern, responsive styling system
	Framer Motion	Premium micro-animations & transitions
	Recharts	Interactive weakness/strength progression graphs
	KaTeX / remark-math	Fast, high-quality typesetting of mathematical notation
Backend	Flask 3.1.0	Light, scalable Python REST API
	Flask-CORS	Enforces Cross-Origin Resource Sharing rules
	google-generativeai SDK	Coordinates with Google's Gemini models
	pdfplumber	Accurate text extraction from PDF documents
	Pillow	Multi-modal image analysis preparation

🚀 Getting Started

Follow these steps to set up ExamAI locally.

Prerequisites

Node.js 18+
Python 3.10+
A Gemini API Key from Google AI Studio

Step 1: Clone and Configure Environment

In the root of the project, create a file named .env.local and add your Gemini API Key:

GEMINI_API_KEY=your_actual_gemini_api_key_here

Important

The backend automatically searches for .env.local in the root folder, so ensure the path and variable name are exactly as shown.

Step 2: Set Up Backend (Flask)

Navigate to the backend directory:
```
cd backend
```

Create and activate a Python virtual environment:

# Windows
python -m venv venv
.\venv\Scripts\activate

# macOS / Linux
python3 -m venv venv
source venv/bin/activate

Install dependencies:
```
pip install -r requirements.txt
```
Start the server:
```
python app.py
```
The backend starts running at http://localhost:5000/api/.

Step 3: Set Up Frontend (Next.js)

Open a new terminal in the root directory.
Install npm packages:
```
npm install
```
Start the local development server:
```
npm run dev
```
Open http://localhost:3000 in your browser to view the application.

🔌 API Endpoints Reference

The Flask backend exposes the following REST/streaming endpoints under the /api prefix:

Endpoint	Method	Payload (JSON)	Description
`/health`	`GET`	None	Returns backend status.
`/chat`	`POST`	`{"examType": "jee-mains", "message": "..."}`	Queries the AI Tutor with exam-specific context.
`/chat/stream`	`POST`	`{"examType": "gate", "message": "..."}`	Establishes a server-sent events stream for chat responses.
`/generate-test`	`POST`	`{"examType": "gate", "subjects": ["Math"], "difficulty": "hard", "numberOfQuestions": 5}`	Generates a custom mock test in JSON format.
`/submit-test`	`POST`	`{"examType": "jee-advanced", "questions": [...], "userAnswers": [...]}`	Evaluates test attempts, calculates score, and extracts weak topics.
`/upload-question`	`POST`	`FormData` containing a `file`	Parses PDF/Image questions and provides step-by-step solutions.
`/generate-similar`	`POST`	`{"question": "..."}`	Returns 3 variations of the input question with options.
`/performance`	`POST`	`{"testHistory": [...]}`	Generates progression data and topic accuracies for graphs.

📁 Directory Structure

exam-ai/
├── backend/                  # Flask REST Service
│   ├── routes/               # API Blueprints (chat, evaluation, uploads)
│   ├── services/             # Gemini API connector service
│   ├── uploads/              # Temporary storage for student documents
│   ├── utils/                # PDF parsing scripts
│   ├── app.py                # Flask entrypoint
│   ├── config.py             # Environment config & AI system instructions
│   └── requirements.txt      # Python dependencies
├── src/                      # Next.js Frontend
│   ├── app/                  # Next.js App Router (Layouts & Pages)
│   │   ├── (dashboard)/      # Dashboard pages (mock-tests, tutor, performance, results)
│   │   ├── (marketing)/      # Landing page / home screen
│   │   └── test-interface/   # Custom UI for active exam attempts
│   ├── components/           # Custom UI controls & modules (Tutor chat panel, sidebar)
│   ├── lib/                  # Shared utilities (Gemini client, math configuration)
│   └── globals.css           # Global Tailwind CSS definitions
├── .env.local                # Local environment secrets (Shared)
├── package.json              # NPM dependencies & project scripts
└── tsconfig.json             # TypeScript configuration

🤝 Contributing

Fork the repository.
Create a feature branch: git checkout -b feature/NewFeature
Commit your changes: git commit -m 'Add NewFeature'
Push to the branch: git push origin feature/NewFeature
Open a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
backend		backend
public		public
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
components.json		components.json
eslint.config.mjs		eslint.config.mjs
eslint.json		eslint.json
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

Navigation Menu

Repository navigation

About

Repository files navigation

🎓 ExamAI

🏗️ System Architecture

✨ Core Features

💬 1. Interactive AI Tutor (Chat)

📝 2. Dynamic Mock Test Generator

🔬 3. Auto-Evaluation & Performance Diagnostics

📤 4. PDF & Image Question Solver

🔄 5. Similar Question Generator

🛠️ Tech Stack

🚀 Getting Started

Prerequisites

Step 1: Clone and Configure Environment

Step 2: Set Up Backend (Flask)

Step 3: Set Up Frontend (Next.js)

🔌 API Endpoints Reference

📁 Directory Structure

🤝 Contributing

📄 License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

🎓 ExamAI

🏗️ System Architecture

✨ Core Features

💬 1. Interactive AI Tutor (Chat)

📝 2. Dynamic Mock Test Generator

🔬 3. Auto-Evaluation & Performance Diagnostics

📤 4. PDF & Image Question Solver

🔄 5. Similar Question Generator

🛠️ Tech Stack

🚀 Getting Started

Prerequisites

Step 1: Clone and Configure Environment

Step 2: Set Up Backend (Flask)

Step 3: Set Up Frontend (Next.js)

🔌 API Endpoints Reference

📁 Directory Structure

🤝 Contributing

📄 License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages