AI Teaching Assistant - Backend

A modern, scalable backend for an AI-powered teaching assistant that automates grading, provides intelligent feedback, and enables Socratic teaching methods.

🏗️ Architecture Overview

The backend is built with FastAPI and follows modern Python async patterns with a clean, layered architecture:

├── app/                      # Main application code
│   ├── api/                  # API route handlers
│   │   ├── analytics.py      # Analytics & reporting endpoints
│   │   ├── assignments.py    # Assignment management API
│   │   ├── auth.py          # Authentication endpoints
│   │   ├── files.py         # File upload/download API
│   │   ├── grading.py       # AI grading operations
│   │   ├── health.py        # Health check endpoints
│   │   ├── notifications.py # Notification management
│   │   ├── socratic.py      # Socratic teaching API
│   │   ├── submissions.py   # Submission handling
│   │   ├── users.py         # User management
│   │   └── websocket.py     # Real-time WebSocket API
│   ├── core/                # Core functionality & utilities
│   │   ├── auth.py          # Authentication & authorization logic
│   │   ├── config.py        # Application configuration
│   │   ├── events.py        # Application lifecycle events
│   │   ├── exceptions.py    # Custom exception classes
│   │   ├── logging.py       # Structured logging setup
│   │   ├── middleware.py    # HTTP middleware (CORS, logging, etc.)
│   │   ├── monitoring.py    # Prometheus metrics & monitoring
│   │   └── security.py      # Security utilities (password hashing, JWT)
│   ├── db/                  # Database layer
│   │   ├── models/          # SQLAlchemy ORM models
│   │   │   ├── assignment.py    # Assignment model
│   │   │   ├── base.py          # Base model class
│   │   │   ├── notification.py  # Notification model
│   │   │   ├── socratic.py      # Socratic session models
│   │   │   ├── submission.py    # Submission model
│   │   │   └── user.py          # User model with roles
│   │   ├── migrations/      # Alembic database migrations
│   │   ├── repositories/    # Data access layer (Repository pattern)
│   │   │   ├── assignment.py    # Assignment repository
│   │   │   ├── base.py          # Base repository class
│   │   │   ├── notification.py  # Notification repository
│   │   │   ├── socratic.py      # Socratic repository
│   │   │   └── user.py          # User repository
│   │   ├── init_db.py       # Database initialization & seed data
│   │   └── session.py       # Database session management
│   ├── services/            # Business logic services
│   │   ├── document_parser.py   # PDF/document parsing
│   │   ├── grading_agent.py     # AI grading service using LangChain
│   │   ├── socratic.py          # Socratic teaching logic
│   │   ├── vector_store.py      # Vector embeddings & similarity search
│   │   └── websocket.py         # WebSocket connection manager
│   ├── tasks/               # Background tasks (Celery)
│   │   ├── analytics.py     # Analytics data processing
│   │   ├── celery.py        # Celery configuration
│   │   ├── file_processing.py   # File processing tasks
│   │   ├── grading.py       # Async grading tasks
│   │   ├── monitoring.py    # System monitoring tasks
│   │   └── notifications.py # Email/notification tasks
│   └── main.py              # FastAPI application entry point
├── tests/                   # Test suite
├── scripts/                 # Utility scripts
├── data/                    # Data storage (assignments, submissions, etc.)
└── requirements-*.txt       # Dependencies organized by environment

🚀 Quick Start

Prerequisites

• Python 3.10+
• PostgreSQL 14+ (or use Docker)
• Redis 6+ (or use Docker)
• Elasticsearch 8+ (optional, for analytics)

1. Environment Setup

# Clone the repository
git clone <repository-url>
cd ai-ta-grading-agent/backend

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

# Install dependencies
pip install -r requirements-dev.txt  # For development
# OR
pip install -r requirements-core.txt  # For minimal setup

2. Configuration

# Copy environment template
cp .env.example .env

# Edit configuration (required settings)
# - DATABASE_URL: PostgreSQL connection string
# - SECRET_KEY: JWT secret key
# - OPENAI_API_KEY: OpenAI API key for AI grading
# - REDIS_URL: Redis connection string

3. Database Setup

# Initialize database with sample data
python -c "
import asyncio
from app.db.init_db import init_db
asyncio.run(init_db())
"

# Or run migrations manually
alembic upgrade head

4. Start the Application

# Development server (with auto-reload)
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Production server
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker

5. Verify Installation

Visit these URLs to confirm everything is working:

• API Documentation: http://localhost:8000/docs
• Health Check: http://localhost:8000/api/v1/health
• Metrics: http://localhost:8000/metrics

📋 Requirements Structure

We use a modular requirements structure for different environments:

File	Purpose	Usage
requirements-core.txt	28 essential packages	pip install -r requirements-core.txt
requirements-dev.txt	Core + development tools	pip install -r requirements-dev.txt
requirements-prod.txt	Core + production extras	pip install -r requirements-prod.txt
requirements-categorized.txt	Detailed breakdown	Reference documentation

Key Dependencies by Category:

• 🌐 Web Framework: FastAPI, Uvicorn, Starlette, Pydantic
• 🗄️ Database: SQLAlchemy, Alembic, Redis, Elasticsearch
• 🤖 AI/ML: LangChain, OpenAI, Hugging Face, NumPy, Pandas
• 📁 Storage: MinIO, AioFiles
• 🔐 Security: Passlib, Python-JOSE
• 📊 Monitoring: Prometheus, Structlog, Psutil
• ✉️ Communication: AioSMTPLib, Aio-Pika

🔧 Application Startup Flow

How the Application Starts

1. app/main.py - Entry point that creates the FastAPI app
2. create_application() - Configures the app with:
   • Middleware setup (CORS, logging, monitoring)
   • API router registration
   • Event handlers (startup/shutdown)
   • Exception handlers
3. Startup Events - Initialize connections to:
   • Database (PostgreSQL)
   • Cache (Redis)
   • Search (Elasticsearch)
   • Message Queue (RabbitMQ)
4. API Routers - Register all endpoint handlers from app/api/

Main Components Flow:

main.py → create_application() → middleware → routers → services → repositories → models

🧪 Testing & Development

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=app tests/

# Run specific test categories
pytest tests/test_db.py          # Database tests
pytest tests/test_auth.py        # Authentication tests
pytest tests/test_health.py      # Health check tests

Local Development Configuration

For local testing, you can comment/uncomment these in your .env:

# Disable external services for local testing
# ELASTICSEARCH_URL=http://localhost:9200  # Comment out to disable analytics
# RABBITMQ_HOST=localhost                  # Comment out to disable task queue
# MINIO_URL=localhost:9000                 # Comment out to use local file storage

# Use simpler backends for development
DATABASE_URL=sqlite:///./test.db           # Use SQLite instead of PostgreSQL
REDIS_URL=redis://localhost:6379/0         # Use local Redis

📊 Monitoring & Health Checks

Available Endpoints

Endpoint	Purpose	Usage
/api/v1/health	Application health	Basic liveness check
/api/v1/health/detailed	Detailed health	Database, Redis, external services
/metrics	Prometheus metrics	System metrics for monitoring
/docs	API Documentation	Interactive Swagger UI
/redoc	Alternative docs	ReDoc interface

Health Check Response Example:

{
  "status": "healthy",
  "timestamp": "2024-01-20T10:30:00Z",
  "version": "0.1.0",
  "services": {
    "database": "healthy",
    "redis": "healthy",
    "elasticsearch": "healthy"
  }
}

Prometheus Metrics

The application exposes these metrics:

• Request counts by endpoint and status code
• Response times (latency histograms)
• Active connections count
• Database connection pool metrics
• Custom business metrics (grading operations, user activity)

🔐 Authentication & Authorization

User Roles

• 👑 Admin: Full system access
• 👨‍🏫 Instructor: Manage assignments and grade submissions
• 👨‍🎓 TA: Grade submissions and assist students
• 👤 Student: Submit assignments and view feedback

API Authentication

# Login to get JWT token
curl -X POST "/api/v1/auth/login" \
  -d "username=user@example.com&password=password"

# Use token in requests
curl -H "Authorization: Bearer <token>" "/api/v1/assignments"

🐳 Docker Deployment

# Build image
docker build -t ai-ta-backend .

# Run with docker-compose (includes PostgreSQL, Redis)
docker-compose up -d

🔍 Troubleshooting

Common Issues

1. Database Connection Error

   # Check PostgreSQL is running
   pg_isready -h localhost -p 5432
   
   # Verify connection string in .env
   DATABASE_URL=postgresql://user:password@localhost:5432/dbname

2. OpenAI API Errors

   # Verify API key is set
   echo $OPENAI_API_KEY
   
   # Test API key
   curl -H "Authorization: Bearer $OPENAI_API_KEY" \
        https://api.openai.com/v1/models

3. Import Errors

   # Ensure virtual environment is activated
   which python  # Should show venv path
   
   # Reinstall dependencies
   pip install -r requirements-dev.txt

Debug Mode

# Enable debug logging
export LOG_LEVEL=DEBUG

# Run with reload and debug
uvicorn app.main:app --reload --log-level debug

📈 Performance & Scaling

Current Capabilities

• Async I/O: All database and external service calls are async
• Connection Pooling: PostgreSQL and Redis connection pools
• Caching: Multi-level caching strategy with Redis
• Background Tasks: Celery for heavy operations (grading, analytics)

Scaling Options

• Horizontal: Add more FastAPI workers/containers
• Database: PostgreSQL read replicas
• Cache: Redis cluster
• Storage: S3/MinIO for file storage
• Search: Elasticsearch cluster for analytics

🤝 Contributing

1. Follow PEP 8 code style
2. Add type hints to all functions
3. Write tests for new features
4. Update documentation for API changes
5. Use conventional commit messages

📄 License

MIT License - see LICENSE file for details.

---