# ibrahim2789/smartgrid-ai architecture

> Architecture diagram of the GitHub repository ibrahim2789/smartgrid-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ibrahim2789/smartgrid-ai
- Repository: https://github.com/ibrahim2789/smartgrid-ai

## Overview

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: [`backend/app/router.py`](https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/router.py) (API Router), [`frontend/src/App.tsx`](https://github.com/ibrahim2789/smartgrid-ai/blob/main/frontend/src/App.tsx) (Application Shell), [`backend/app/routers/optimization.py`](https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/routers/optimization.py) (Optimization API), [`backend/app/deps.py`](https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/deps.py) (Request and Auth Helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User Workflows"]
  node_app["Application Shell<br/>[App.tsx]"]
  node_setup["Institution Setup<br/>[SetupFlow.tsx]"]
  node_import_ui["Data Import"]
  node_generator["Timetable Generation<br/>[GenerateScreen.tsx]"]
  node_feedback["Schedule Feedback<br/>[FeedbackScreen.tsx]"]
  node_voting_ui["Student Voting"]
  node_store[("Institutional State<br/>[store.ts]")]
  node_api_client["Voting API Client<br/>[votingApi.ts]"]
end

subgraph group_api["Backend Services"]
  node_router["API Router<br/>[router.py]"]
  node_institutions["Institution Services<br/>[institutions.py]"]
  node_catalog["Academic Catalog<br/>[catalog.py]"]
  node_imports["Import Processing<br/>[csv_import.py]"]
  node_voting["Voting Services<br/>[voting.py]"]
  node_optimization_api["Optimization API<br/>[optimization.py]"]
  node_rescheduling_api["Rescheduling API<br/>[rescheduling.py]"]
  node_deps["Request and Auth Helpers<br/>[deps.py]"]
end

subgraph group_solver["Scheduling Engine"]
  node_constraints["Scheduling Model<br/>[constraints.py]"]
  node_coloring["DSatur Coloring<br/>[graph_coloring.py]"]
  node_genetic["Genetic Search"]
  node_fitness["Fitness and Fairness<br/>[fitness.py]"]
  node_annealing["Local Refinement"]
  node_tabu["Tabu Search<br/>[tabu_search.py]"]
  node_rescheduler["Schedule Repair<br/>[rescheduler.py]"]
end

subgraph group_data["Persistence"]
  node_supabase[("Supabase Postgres<br/>[supabase.py]")]
end

node_users(("Institutional Users"))

node_users -->|"uses"| node_app
node_app -->|"renders"| node_setup
node_app -->|"renders"| node_generator
node_app -->|"renders"| node_feedback
node_app -->|"routes to"| node_voting_ui
node_setup -->|"updates"| node_store
node_import_ui -.->|"imports into"| node_store
node_app -->|"loads institutions"| node_api_client
node_api_client -.->|"HTTP requests"| node_router
node_router -->|"mounts"| node_institutions
node_router -->|"mounts"| node_catalog
node_router -->|"mounts"| node_voting
node_router -->|"mounts"| node_optimization_api
node_router -->|"mounts"| node_rescheduling_api
node_router -->|"mounts routes"| node_imports
node_institutions -->|"uses helpers"| node_deps
node_catalog -->|"uses helpers"| node_deps
node_voting -->|"uses helpers"| node_deps
node_optimization_api -->|"uses helpers"| node_deps
node_rescheduling_api -->|"uses helpers"| node_deps
node_deps -->|"queries"| node_supabase
node_optimization_api -->|"loads scheduling model"| node_constraints
node_optimization_api -->|"evaluates schedules"| node_fitness
node_optimization_api -.->|"seeds schedules"| node_coloring
node_optimization_api -.->|"searches candidates"| node_genetic
node_genetic -.->|"refines best schedule"| node_annealing
node_fitness -->|"checks feasibility"| node_constraints
node_rescheduling_api -->|"requests repair"| node_rescheduler
node_rescheduling_api -->|"loads constraints"| node_constraints
node_rescheduler -.->|"searches changes"| node_tabu
node_institutions -->|"persists records"| node_supabase
node_catalog -->|"reads and writes"| node_supabase
node_voting -->|"stores votes"| node_supabase
node_imports -->|"persists imported data"| node_supabase

click node_app "https://github.com/ibrahim2789/smartgrid-ai/blob/main/frontend/src/App.tsx"
click node_setup "https://github.com/ibrahim2789/smartgrid-ai/blob/main/frontend/src/components/SetupFlow.tsx"
click node_import_ui "https://github.com/ibrahim2789/smartgrid-ai/blob/main/frontend/src/components/DataImportWizard.tsx"
click node_generator "https://github.com/ibrahim2789/smartgrid-ai/blob/main/frontend/src/components/GenerateScreen.tsx"
click node_feedback "https://github.com/ibrahim2789/smartgrid-ai/blob/main/frontend/src/components/FeedbackScreen.tsx"
click node_voting_ui "https://github.com/ibrahim2789/smartgrid-ai/blob/main/frontend/src/components/StudentVotingPage.tsx"
click node_store "https://github.com/ibrahim2789/smartgrid-ai/blob/main/frontend/src/data/store.ts"
click node_api_client "https://github.com/ibrahim2789/smartgrid-ai/blob/main/frontend/src/services/votingApi.ts"
click node_router "https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/router.py"
click node_institutions "https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/routers/institutions.py"
click node_catalog "https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/routers/catalog.py"
click node_imports "https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/services/csv_import.py"
click node_voting "https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/routers/voting.py"
click node_optimization_api "https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/routers/optimization.py"
click node_rescheduling_api "https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/routers/rescheduling.py"
click node_deps "https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/deps.py"
click node_constraints "https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/optimization/constraints.py"
click node_coloring "https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/optimization/graph_coloring.py"
click node_genetic "https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/optimization/genetic_algorithm.py"
click node_fitness "https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/optimization/fitness.py"
click node_annealing "https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/optimization/simulated_annealing.py"
click node_tabu "https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/optimization/tabu_search.py"
click node_rescheduler "https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/optimization/rescheduler.py"
click node_supabase "https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/database/supabase.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_setup,node_import_ui,node_generator,node_feedback,node_voting_ui,node_store,node_api_client,node_users toneBlue
class node_router,node_institutions,node_catalog,node_imports,node_voting,node_optimization_api,node_rescheduling_api,node_deps toneAmber
class node_constraints,node_coloring,node_genetic,node_fitness,node_annealing,node_tabu,node_rescheduler toneMint
class node_supabase toneRose
```

## Components

### User Workflows

- [Application Shell](https://github.com/ibrahim2789/smartgrid-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Institution Setup](https://github.com/ibrahim2789/smartgrid-ai/blob/main/frontend/src/components/SetupFlow.tsx): `frontend/src/components/SetupFlow.tsx`
- [Data Import](https://github.com/ibrahim2789/smartgrid-ai/blob/main/frontend/src/components/DataImportWizard.tsx): `frontend/src/components/DataImportWizard.tsx`
- [Timetable Generation](https://github.com/ibrahim2789/smartgrid-ai/blob/main/frontend/src/components/GenerateScreen.tsx): `frontend/src/components/GenerateScreen.tsx`
- [Schedule Feedback](https://github.com/ibrahim2789/smartgrid-ai/blob/main/frontend/src/components/FeedbackScreen.tsx): `frontend/src/components/FeedbackScreen.tsx`
- [Student Voting](https://github.com/ibrahim2789/smartgrid-ai/blob/main/frontend/src/components/StudentVotingPage.tsx): `frontend/src/components/StudentVotingPage.tsx`
- [Institutional State](https://github.com/ibrahim2789/smartgrid-ai/blob/main/frontend/src/data/store.ts): `frontend/src/data/store.ts`
- [Voting API Client](https://github.com/ibrahim2789/smartgrid-ai/blob/main/frontend/src/services/votingApi.ts): `frontend/src/services/votingApi.ts`

### Backend Services

- [API Router](https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/router.py): `backend/app/router.py`
- [Institution Services](https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/routers/institutions.py): `backend/app/routers/institutions.py`
- [Academic Catalog](https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/routers/catalog.py): `backend/app/routers/catalog.py`
- [Import Processing](https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/services/csv_import.py): `backend/app/services/csv_import.py`
- [Voting Services](https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/routers/voting.py): `backend/app/routers/voting.py`
- [Optimization API](https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/routers/optimization.py): `backend/app/routers/optimization.py`
- [Rescheduling API](https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/routers/rescheduling.py): `backend/app/routers/rescheduling.py`
- [Request and Auth Helpers](https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/deps.py): `backend/app/deps.py`

### Scheduling Engine

- [Scheduling Model](https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/optimization/constraints.py): `backend/app/optimization/constraints.py`
- [DSatur Coloring](https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/optimization/graph_coloring.py): `backend/app/optimization/graph_coloring.py`
- [Genetic Search](https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/optimization/genetic_algorithm.py): `backend/app/optimization/genetic_algorithm.py`
- [Fitness and Fairness](https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/optimization/fitness.py): `backend/app/optimization/fitness.py`
- [Local Refinement](https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/optimization/simulated_annealing.py): `backend/app/optimization/simulated_annealing.py`
- [Tabu Search](https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/optimization/tabu_search.py): `backend/app/optimization/tabu_search.py`
- [Schedule Repair](https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/optimization/rescheduler.py): `backend/app/optimization/rescheduler.py`

### Persistence

- [Supabase Postgres](https://github.com/ibrahim2789/smartgrid-ai/blob/main/backend/app/database/supabase.py): `backend/app/database/supabase.py`

### Other components

- **Institutional Users**

## Connections

- Institutional Users → Application Shell: uses (evidence: `frontend/src/App.tsx`)
- Application Shell → Institution Setup: renders (evidence: `frontend/src/App.tsx`)
- Application Shell → Timetable Generation: renders (evidence: `frontend/src/App.tsx`)
- Application Shell → Schedule Feedback: renders (evidence: `frontend/src/App.tsx`)
- Application Shell → Student Voting: routes to (evidence: `frontend/src/App.tsx`)
- Institution Setup → Institutional State: updates (evidence: `frontend/src/data/store.ts`)
- Data Import → Institutional State: imports into
- Application Shell → Voting API Client: loads institutions (evidence: `frontend/src/App.tsx`)
- Voting API Client → API Router: HTTP requests
- API Router → Institution Services: mounts (evidence: `backend/app/router.py`)
- API Router → Academic Catalog: mounts (evidence: `backend/app/router.py`)
- API Router → Voting Services: mounts (evidence: `backend/app/router.py`)
- API Router → Optimization API: mounts (evidence: `backend/app/router.py`)
- API Router → Rescheduling API: mounts (evidence: `backend/app/router.py`)
- API Router → Import Processing: mounts routes (evidence: `backend/app/router.py`)
- Institution Services → Request and Auth Helpers: uses helpers (evidence: `backend/app/deps.py`)
- Academic Catalog → Request and Auth Helpers: uses helpers (evidence: `backend/app/deps.py`)
- Voting Services → Request and Auth Helpers: uses helpers (evidence: `backend/app/deps.py`)
- Optimization API → Request and Auth Helpers: uses helpers (evidence: `backend/app/deps.py`)
- Rescheduling API → Request and Auth Helpers: uses helpers (evidence: `backend/app/deps.py`)
- Request and Auth Helpers → Supabase Postgres: queries (evidence: `backend/app/deps.py`)
- Optimization API → Scheduling Model: loads scheduling model (evidence: `backend/app/routers/optimization.py`)
- Optimization API → Fitness and Fairness: evaluates schedules (evidence: `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 (evidence: `backend/app/optimization/fitness.py`)
- Rescheduling API → Schedule Repair: requests repair (evidence: `backend/app/routers/rescheduling.py`)
- Rescheduling API → Scheduling Model: loads constraints (evidence: `backend/app/routers/rescheduling.py`)
- Schedule Repair → Tabu Search: searches changes
- Institution Services → Supabase Postgres: persists records (evidence: `backend/app/routers/institutions.py`)
- Academic Catalog → Supabase Postgres: reads and writes (evidence: `backend/app/routers/catalog.py`)
- Voting Services → Supabase Postgres: stores votes (evidence: `backend/app/routers/voting.py`)
- Import Processing → Supabase Postgres: persists imported data (evidence: `backend/app/services/csv_import.py`)
