How ibrahim2789/smartgrid-ai works
SmartGrid AI is a multi-university timetable planning and student batch-voting platform. Users configure institutional academic data, import it, generate and review optimized timetables, collect student preferences and votes, and adapt schedules to disruptions. The frontend serves role-specific workflows; FastAPI routes requests into institutional, voting, import, scheduling, and rescheduling domains, with Supabase providing persistence. The README documents the optimization stages; some internal algorithm connections and UI-to-endpoint details are not shown in sampled source, so those links are omitted or marked unverified.
Main entry points: router.py API Router · App.tsx Application Shell · optimization.py Optimization API · deps.py Request and Auth Helpers
Components 25
User Workflows
- Application Shell
frontend/src/App.tsx - Institution Setup
frontend/src/components/SetupFlow.tsx - Data Import
frontend/src/components/DataImportWizard.tsx - Timetable Generation
frontend/src/components/GenerateScreen.tsx - Schedule Feedback
frontend/src/components/FeedbackScreen.tsx - Student Voting
frontend/src/components/StudentVotingPage.tsx - Institutional State
frontend/src/data/store.ts - Voting API Client
frontend/src/services/votingApi.ts
Backend Services
- API Router
backend/app/router.py - Institution Services
backend/app/routers/institutions.py - Academic Catalog
backend/app/routers/catalog.py - Import Processing
backend/app/services/csv_import.py - Voting Services
backend/app/routers/voting.py - Optimization API
backend/app/routers/optimization.py - Rescheduling API
backend/app/routers/rescheduling.py - Request and Auth Helpers
backend/app/deps.py
Scheduling Engine
- Scheduling Model
backend/app/optimization/constraints.py - DSatur Coloring
backend/app/optimization/graph_coloring.py - Genetic Search
backend/app/optimization/genetic_algorithm.py - Fitness and Fairness
backend/app/optimization/fitness.py - Local Refinement
backend/app/optimization/simulated_annealing.py - Tabu Search
backend/app/optimization/tabu_search.py - Schedule Repair
backend/app/optimization/rescheduler.py
Persistence
- Supabase Postgres
backend/app/database/supabase.py
Other components
- Institutional Users
Connections 34
- Institutional Users → Application Shell: uses
frontend/src/App.tsx - Application Shell → Institution Setup: renders
frontend/src/App.tsx - Application Shell → Timetable Generation: renders
frontend/src/App.tsx - Application Shell → Schedule Feedback: renders
frontend/src/App.tsx - Application Shell → Student Voting: routes to
frontend/src/App.tsx - Institution Setup → Institutional State: updates
frontend/src/data/store.ts - Data Import → Institutional State: imports into
- Application Shell → Voting API Client: loads institutions
frontend/src/App.tsx - Voting API Client → API Router: HTTP requests
- API Router → Institution Services: mounts
backend/app/router.py - API Router → Academic Catalog: mounts
backend/app/router.py - API Router → Voting Services: mounts
backend/app/router.py - API Router → Optimization API: mounts
backend/app/router.py - API Router → Rescheduling API: mounts
backend/app/router.py - API Router → Import Processing: mounts routes
backend/app/router.py - Institution Services → Request and Auth Helpers: uses helpers
backend/app/deps.py - Academic Catalog → Request and Auth Helpers: uses helpers
backend/app/deps.py - Voting Services → Request and Auth Helpers: uses helpers
backend/app/deps.py - Optimization API → Request and Auth Helpers: uses helpers
backend/app/deps.py - Rescheduling API → Request and Auth Helpers: uses helpers
backend/app/deps.py - Request and Auth Helpers → Supabase Postgres: queries
backend/app/deps.py - Optimization API → Scheduling Model: loads scheduling model
backend/app/routers/optimization.py - Optimization API → Fitness and Fairness: evaluates schedules
backend/app/routers/optimization.py - Optimization API → DSatur Coloring: seeds schedules
- Optimization API → Genetic Search: searches candidates
- Genetic Search → Local Refinement: refines best schedule
- Fitness and Fairness → Scheduling Model: checks feasibility
backend/app/optimization/fitness.py - Rescheduling API → Schedule Repair: requests repair
backend/app/routers/rescheduling.py - Rescheduling API → Scheduling Model: loads constraints
backend/app/routers/rescheduling.py - Schedule Repair → Tabu Search: searches changes
- Institution Services → Supabase Postgres: persists records
backend/app/routers/institutions.py - Academic Catalog → Supabase Postgres: reads and writes
backend/app/routers/catalog.py - Voting Services → Supabase Postgres: stores votes
backend/app/routers/voting.py - Import Processing → Supabase Postgres: persists imported data
backend/app/services/csv_import.py