Skip to main content

​
Architecture Overview

EduMate is an AI-powered educational assessment platform that generates multiple-choice questions based on PDF documents using Bloom’s Taxonomy. The system consists of several interconnected components working together to provide a seamless experience.

​
System Architecture

​
Infrastructure Components

1

PostgreSQL Database

Stores user accounts, authentication data, and assessment history
  • Port: 5432
  • Database: edumate
  • User: edumate_user
2

Qdrant Vector Database

Stores document embeddings for semantic search
  • Port: 6333
  • Collections: Dynamic (created per uploaded document)
3

Redis Queue

Manages background job processing for document chunking and question generation
  • Port: 6379
  • Queue: RQ (Redis Queue)
4

Ollama

Provides local LLM inference for embeddings and chat
  • Port: 11434
  • Models: qwen3-embedding:0.6b, llama3.2:1b
5

Gemini API

External API for advanced question generation
  • Model: gemini-2.5-flash-lite
  • API: Google Generative Language API
6

FastAPI Backend

RESTful API server handling all business logic
  • Port: 8000
  • Framework: FastAPI with Uvicorn
7

React Frontend

Modern web interface built with React and Vite
  • Dev Port: 5173 (default Vite)
  • Framework: React 19 with React Router

​
System Requirements

​
Hardware Requirements

Minimum Requirements
  • CPU: 4 cores (8 cores recommended)
  • RAM: 8GB (16GB recommended for Ollama models)
  • Storage: 20GB free space
  • GPU: Optional (improves Ollama performance)

​
Software Requirements

  • Operating System: Linux (Ubuntu 20.04+), macOS, or Windows with WSL2
  • Python: 3.9 or higher
  • Node.js: 18.x or higher
  • PostgreSQL: 13 or higher
  • Redis: 6.x or higher
  • Docker: Optional (for Qdrant)

​
Deployment Workflow

1

Set Up Databases

Install and configure PostgreSQL and Qdrant vector databaseSee: Database Setup and Vector Database Setup
2

Install Ollama

Install Ollama and download required AI modelsSee: Ollama Setup
3

Deploy Backend

Configure Python environment and start the FastAPI serverSee: Backend Deployment
4

Deploy Frontend

Build and serve the React applicationSee: Frontend Deployment
5

Start Services

Launch all required services in the correct order:
  1. PostgreSQL
  2. Redis
  3. Qdrant
  4. Ollama
  5. RQ Worker
  6. FastAPI Backend
  7. React Frontend (development) or serve built files

​
Network Ports

Ensure the following ports are available:
ServicePortProtocolDescription
FastAPI8000HTTPBackend API server
Vite Dev Server5173HTTPFrontend dev server
PostgreSQL5432TCPDatabase
Redis6379TCPQueue backend
Qdrant6333HTTPVector database
Ollama11434HTTPLLM inference
Make sure all ports are free before starting the deployment. Use netstat -tuln or lsof -i to check port availability.

​
Environment Variables

The following environment variables need to be configured: 
# Gemini API (Required for question generation)
GEMINI_API_KEY=your_gemini_api_key_here

# Database (configured in backend/database.py)
DATABASE_URL=postgresql://edumate_user:edumate_pass@localhost:5432/edumate

# JWT Secret (configured in backend/server.py)
SECRET_KEY=super_secret_edumate_key
Create a .env file in the project root to store environment variables. The backend uses python-dotenv to load these automatically.

​
Next Steps

Follow the deployment guides in order:
  1. Database Setup - Set up PostgreSQL
  2. Vector Database Setup - Configure Qdrant
  3. Ollama Setup - Install and configure Ollama
  4. Backend Deployment - Deploy the FastAPI server
  5. Frontend Deployment - Build and serve the React app

Build docs developers (and LLMs) love

Get started for freeTalk to us