Edulight - AI-Powered Education Platform

Deliver personalized learning experiences at scale with a robust, AI-driven educational backend. Engineered for EdTech startups, universities, and online academies, Edulight seamlessly handles thousands of concurrent students while processing heavy AI generation tasks in the background, boasting a 99.9% uptime architecture.

• Serve millions of requests daily with a high-performance, fully asynchronous FastAPI architecture.
• Process heavy AI tasks invisibly using distributed Celery workers and a Redis message broker.
• Secure student data comprehensively with Supabase authentication, JWT tokens, and PostgreSQL row-level policies.
• Stream real-time class notifications and instant grading updates through integrated WebSockets.
• Store rich educational assets reliably using S3-compatible MinIO integration.
• Scale out infinitely using our provided Docker Swarm and Kubernetes-ready configurations.

Launch the entire Edulight microservices ecosystem locally in under 5 minutes.

# 1. Clone the repository
git clone https://github.com/quangkmhd/edulight.git
cd edulight

# 2. Copy the environment template
cp .env.example .env
# Edit .env with your specific keys if necessary

# 3. Start all services using the provided script
./start_all.sh
# Alternatively, use docker directly: docker-compose up -d

Expected Output:

Starting PostgreSQL... Done
Starting Redis... Done
Starting MinIO... Done
Starting Celery Workers... Done
Starting FastAPI Backend... Done

Edulight is now running! 
API Documentation available at: http://localhost:8000/docs

Choose the deployment method tailored to your infrastructure.

The easiest way to spin up the database, cache, workers, and API simultaneously.

# Ensure Docker and docker-compose are installed
docker-compose build
docker-compose up -d

# View logs to ensure healthy startup
docker-compose logs -f backend

If you need to debug the Python code directly outside of a container.

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Start local dependencies (Postgres, Redis) manually or via a partial docker-compose
# Apply database migrations
alembic upgrade head

# Run the FastAPI server
uvicorn backend.main:app --reload --port 8000

Problem: A client application needs to securely log in a student and receive a JWT token.

# Python Client Example using requests
import requests

response = requests.post(
    "http://localhost:8000/api/v1/auth/login",
    data={"username": "student@example.com", "password": "securepassword"}
)

token = response.json().get("access_token")
headers = {"Authorization": f"Bearer {token}"}
print(f"Successfully authenticated. Token: {token[:10]}...")

Concept: Edulight uses standard OAuth2 Password Bearer flows, making it instantly compatible with mobile apps and web frontends.

Problem: Generating comprehensive feedback on a student's essay using an LLM takes 10 seconds. You cannot block the HTTP request.

# Submit the essay for grading via CURL
curl -X POST "http://localhost:8000/api/v1/assignments/grade" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"submission_id": "12345", "essay_text": "The American Revolution was..."}'

Expected Output:

{
  "task_id": "8a7b6c5d-4e3f-2g1h-9i8j",
  "status": "Processing",
  "message": "Grading task queued successfully."
}

Concept: The FastAPI endpoint instantly returns a task_id. Behind the scenes, a Celery worker picks up the task, calls the AI model (e.g., Dashscope, Gemini), and updates the database upon completion.

Problem: The frontend needs to notify the student the moment their assignment grading is complete.

// JavaScript WebSocket Client
const ws = new WebSocket(`ws://localhost:8000/ws/notifications?token=${jwtToken}`);

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    if (data.type === 'GRADING_COMPLETE') {
        alert(`Your grade is ready! Score: ${data.score}/100`);
    }
};

ws.onopen = () => console.log("Connected to Edulight Real-Time Server");

Concept: Edulight leverages FastAPI's native WebSocket support to maintain persistent connections, pushing critical updates instantly without client-side polling.

• Alembic Migration Failures:
  • Cause: The PostgreSQL database URL in alembic.ini or .env is incorrect or the database isn't ready.
  • Solution: Ensure Postgres is fully initialized (docker ps). Run alembic current to check migration state, then alembic upgrade head.
• Celery Tasks Pending Indefinitely:
  • Cause: The Redis broker is unreachable, or the Celery worker process crashed.
  • Solution: Run ./status_all.sh to check worker health. Inspect worker logs via docker-compose logs worker.
• MinIO Upload Errors (HTTP 403/500):
  • Cause: Invalid S3 bucket policies or incorrect access keys in the .env file.
  • Solution: Log into the MinIO console (http://localhost:9001), verify the edulight-assets bucket exists, and regenerate the access keys.

• Complete API Reference (Swagger)
  Interact directly with the live endpoints powering the Edulight platform. This auto-generated Swagger UI provides exhaustive details on request payloads, authentication schemas, and available parameters, allowing you to test out the robust FastAPI backend instantly.

• Database Schema & Migrations
  Uncover the structural foundation of our multi-tenant educational platform through detailed PostgreSQL schema diagrams. Learn how Alembic migrations ensure row-level security and data integrity for thousands of concurrent students and complex course relationships.

• Celery Task Configuration
  Master the asynchronous engine that handles intensive AI workloads without slowing down user interactions. This guide explains how to tune Redis message brokers and configure distributed Celery workers for maximum throughput and 99.9% uptime.

• AI Model Integration Guide
  Explore the secrets of Edulight's personalized learning algorithms and automated grading features. Discover how we orchestrate connections to cutting-edge LLMs, handle prompt engineering at scale, and manage asynchronous AI inference tasks flawlessly.

We invite educators, engineers, and designers to contribute to Edulight!

1. Fork the repository on GitHub.
2. Create a feature branch (git checkout -b feature/new-quiz-module).
3. Commit your changes with descriptive messages.
4. Run the test suite (pytest tests/).
5. Push and submit a Pull Request.

Please review our Code of Conduct before participating.

Edulight is released under the MIT License. See the LICENSE file for details.

• Built heavily upon FastAPI.
• Asynchronous task queuing by Celery.
• AI capabilities powered by standard LLM APIs.