EduSim AI — AI-Powered Interactive STEM & Engineering Learning Platform

Learn. Simulate. Build.
An AI-powered interactive learning platform where school and college students understand concepts through 3D visualization, virtual simulation, hands-on project engineering, and AI mentorship.

---

Architecture Overview

EduSim AI Platform
├── frontend/                  # React (Vite) + Tailwind CSS + Three.js + Recharts
│   ├── src/
│   │   ├── components/        # Three.js SimulationEngine, CodeEditor, AI Mentor, Stepper
│   │   ├── pages/             # Landing, Dashboard, AI Tutor, Simulation Lab, Project Lab, Quizzes, Progress, Admin, Teacher
│   │   ├── layouts/           # Responsive Main & Dashboard layouts
│   │   ├── context/           # AuthContext & Session management
│   │   └── services/          # Axios API clients
│   └── Dockerfile             # Multi-stage production Nginx container
│
├── backend/                   # Python FastAPI + SQLAlchemy + Pydantic + PyJWT
│   ├── app/
│   │   ├── models/            # 10 PostgreSQL/SQLite relational models
│   │   ├── schemas/           # Pydantic validation & serialization models
│   │   ├── routes/            # Complete REST endpoints (/auth, /courses, /simulations, /projects, /ai, etc.)
│   │   ├── services/          # Pluggable AIService (mock & LLM connector architecture)
│   │   ├── auth/              # Bcrypt password hashing & JWT token validation
│   │   └── database/          # Database engine and automatic seed runner
│   └── Dockerfile             # Python 3.11 container
│
├── docker-compose.yml         # Multi-service orchestration (PostgreSQL + FastAPI + React)
└── .env.example               # Complete environment variable specification

---

Quick Demo Credentials

For testing and demonstration, technical seed accounts are pre-configured:

Role	Email	Password	Dashboard URL
Student	student@edusim.ai	password123	/dashboard
Teacher	teacher@edusim.ai	password123	/teacher
Admin	admin@edusim.ai	password123	/admin

(You can also use the "Demo Switcher" button in the top navigation bar or the 1-click pills on the Login screen).

---

1. Installation

Prerequisites

• Node.js: v18+ (tested with v20 and v24)
• Python: 3.10+ (tested with 3.11 and 3.14)
• Git (optional)
• Docker & Docker Compose (optional for containerized deployment)

Clone / Navigate

cd c:/Users/itzvi/Learning

Backend Dependencies

cd backend
pip install -r requirements.txt

Frontend Dependencies

cd ../frontend
npm install

---

2. Environment Variables

Create .env in the root (or backend/.env) using .env.example:

# Database Connection
# Default local development fallback (SQLite, zero configuration needed):
DATABASE_URL=sqlite:///./edusim.db

# PostgreSQL Production Connection:
# DATABASE_URL=postgresql://edusim_user:edusim_password_secure@localhost:5432/edusim_db

# JWT Security
SECRET_KEY=edusim_super_secret_jwt_key_2026_dev_mode_only_change_in_prod
ACCESS_TOKEN_EXPIRE_MINUTES=1440

# AI Provider ("mock", "openai", or "gemini")
AI_PROVIDER=mock
OPENAI_API_KEY=
GEMINI_API_KEY=

Frontend .env (frontend/.env):

VITE_API_URL=http://localhost:8000/api

---

3. Database Setup

The backend automatically creates all 10 relational tables and seeds the 3 demo users on first boot.

To manually initialize or reset the database:

cd backend
python -m app.database.init_db

Relational Database Schema

• User: id, name, email, password_hash, role, education_level, branch, created_at
• Course: id, title, description, education_level, branch, thumbnail, status, created_at
• Module: id, course_id, title, description, order
• Lesson: id, module_id, title, content, difficulty, order
• Simulation: id, title, description, category, configuration, status
• Project: id, title, description, education_level, branch, difficulty, status
• Quiz: id, lesson_id, title, difficulty
• Question: id, quiz_id, question, options, correct_answer, explanation
• StudentProgress: id, user_id, course_id, lesson_id, completion_percentage, score, last_accessed
• ProjectProgress: id, user_id, project_id, current_stage, status, progress, last_updated

---

4. Running Locally

Start Backend Service (FastAPI)

cd backend
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

• API Docs (Swagger UI): http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• Health Check: http://localhost:8000/api/health

Start Frontend Service (React + Vite)

In a separate terminal:

cd frontend
npm run dev

• Open browser at: http://localhost:5173

---

5. Running with Docker Compose

To launch the full stack (PostgreSQL 16 + FastAPI + React on Nginx) with a single command:

docker-compose up --build

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• PostgreSQL: localhost:5432

---

6. API Structure & Endpoints

All endpoints are prefixed with /api:

Domain	Route	Method	Description
Auth	/api/auth/register	POST	Register student/teacher/admin
	/api/auth/login	POST	Authenticate & return signed JWT
	/api/auth/me	GET	Current user profile
	/api/auth/forgot-password	POST	Password recovery dispatcher
Users	/api/users	GET	List users (Admin/Teacher)
	/api/users/{id}	GET, PUT, DELETE	User CRUD operations
Courses	/api/courses	GET, POST	List and create courses
	/api/courses/{id}	GET, PUT, DELETE	Course details & updates
Modules	/api/modules	POST, PUT, DELETE	Curriculum modules
	/api/modules/by-course/{id}	GET	Get modules in course
Lessons	/api/lessons	POST, PUT, DELETE	Lesson content & difficulty
	/api/lessons/by-module/{id}	GET	Get lessons in module
Simulations	/api/simulations	GET, POST, PUT, DELETE	Simulation engine registry
Projects	/api/projects	GET, POST, PUT, DELETE	8-stage project records
	/api/projects/{id}/ai-review	POST	Automated AI code & stage audit
Quizzes	/api/quizzes	GET, POST, PUT, DELETE	Assessment definitions
	/api/quizzes/{id}/submit	POST	Automated quiz scoring
Questions	/api/questions	POST, PUT, DELETE	Multiple choice question items
Progress	/api/progress/dashboard	GET	Learning metrics & streaks
	/api/progress/student	GET, POST	Progress recording
	/api/progress/project/{id}	GET, POST	Project stage saving
	/api/progress/analytics	GET	Admin platform statistics
AI	/api/ai/chat	POST	AI Tutor pedagogical chat
	/api/ai/explain	POST	Structured concept explanation
	/api/ai/hint	POST	Socratic problem hint
	/api/ai/quiz-generate	POST	Dynamic question generation
	/api/ai/analyze-progress	POST	Adaptive learning guidance

---

7. How to Add Courses Later

The application is purposefully designed with zero hardcoded educational courses. Courses, modules, and lessons can be populated dynamically:

Option A: Via the Admin / Teacher Panel

1. Log in with admin@edusim.ai (or teacher@edusim.ai).
2. Navigate to Admin Console (/admin) or Teacher Studio (/teacher).
3. Under the Courses tab, click "Add Course".
4. Enter the Title, Description, Branch, and Education Level.
5. The course will immediately render in the student dashboard and course catalog!

Option B: Via REST API

curl -X POST http://localhost:8000/api/courses \
  -H "Authorization: Bearer <ADMIN_OR_TEACHER_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Autonomous Vehicle Control Systems",
    "description": "State-space modeling, Kalman filtering, and PID trajectory tracking.",
    "branch": "Robotics & Automation",
    "education_level": "college",
    "status": "published"
  }'

---

8. How to Connect an AI Model Later

The AI architecture strictly isolates LLM calls behind the AIService class in backend/app/services/ai_service.py:

Student ──> React Frontend ──> FastAPI ──> AIService ──> LLM Provider (OpenAI / Gemini / Claude)

To connect OpenAI or Google Gemini:

1. Set the environment variable in .env:

   AI_PROVIDER=openai
   OPENAI_API_KEY=sk-...
   # or
   AI_PROVIDER=gemini
   GEMINI_API_KEY=AIza...

2. In backend/app/services/ai_service.py, update _call_openai_chat() or _call_gemini_chat() with your preferred client library:

   # Example OpenAI integration:
   from openai import OpenAI
   client = OpenAI(api_key=self.openai_key)
   response = client.chat.completions.create(
       model="gpt-4o",
       messages=[{"role": m.role, "content": m.content} for m in messages]
   )
   return AIChatResponse(response=response.choices[0].message.content)

---

9. How to Add Simulations Later

All simulations in EduSim AI share the standardized SimulationEngine framework located at: frontend/src/components/simulation/SimulationEngine.js

Steps to add a new 3D simulation:

1. Define the Simulation Type: Add a new identifier (e.g. 'quantum_tunneling').
2. Implement the 3D Scene Builder: In SimulationEngine.js:

   buildSimulationObjects() {
     if (this.type === 'quantum_tunneling') {
       this.buildQuantumBarrier();
     }
     // ...
   }

3. Hook up the Update Loop: Inside this.start(), animate the objects based on this.params and this.time.
4. Register in the Gallery: In frontend/src/pages/SimulationLabPage.jsx, add the configuration to frameworkTemplates with its category, title, description, and slider parameters.
5. The simulation will immediately be playable in the full 3-column viewer with real-time controls, 3D canvas, and AI explanation!

---

License & Integrity

EduSim AI is designed for scalable engineering education, interactive laboratory learning, and AI-guided technical curriculum development.