# adi02surana/elective-allocation-system architecture

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

- Interactive diagram: https://gitdiagram.com/adi02surana/elective-allocation-system
- Repository: https://github.com/adi02surana/elective-allocation-system

## Overview

ECAS collects ranked elective preferences, validates student/course eligibility, runs a deterministic capacity-constrained allocation, and exposes outcomes and institutional reports through role-specific screens. The browser communicates with a local REST API and SQLite backend; frontend storage also maintains seed-backed state. The graph preserves the documented faculty, allocation-administration, reporting, audit, and reset capabilities. Some page and service implementations were not excerpted, so their relationships are included only where the source index or README documents them.

Main entry points: [`src/App.jsx`](https://github.com/adi02surana/elective-allocation-system/blob/main/src/App.jsx) (App navigation), [`server/routes/apiRouter.js`](https://github.com/adi02surana/elective-allocation-system/blob/main/server/routes/apiRouter.js) (REST API router), [`src/services/electiveService.js`](https://github.com/adi02surana/elective-allocation-system/blob/main/src/services/electiveService.js) (Client elective service), [`src/services/storageService.js`](https://github.com/adi02surana/elective-allocation-system/blob/main/src/services/storageService.js) (Client state storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Role-based web app"]
  node_app["App navigation<br/>[App.jsx]"]
  node_login["Login screen<br/>[LoginPage.jsx]"]
  node_student["Student dashboard"]
  node_catalogue["Elective catalogue"]
  node_preferences["Preference builder"]
  node_faculty["Course management"]
  node_allocationadmin["Allocation console"]
  node_result["Student result"]
  node_reports["Analytics and CSV<br/>[ReportsPage.jsx]"]
  node_sysadmin["System administration<br/>[SysAdminPage.jsx]"]
end

subgraph group_client["Client services"]
  node_clientauth["Client authentication<br/>[authService.js]"]
  node_clientcatalogue["Client elective service<br/>[electiveService.js]"]
  node_clientprefs["Client preference service"]
  node_clientalloc["Client allocation service"]
  node_engine["Allocation engine"]
  node_validation["Preference validation"]
  node_clientreports["Client report service<br/>[reportService.js]"]
  node_storage["Client state storage<br/>[storageService.js]"]
  node_seeddata["Canonical seed data<br/>[seedData.js]"]
  node_apiclient["HTTP API client<br/>[apiClient.js]"]
end

subgraph group_backend["API and domain services"]
  node_router["REST API router<br/>[apiRouter.js]"]
  node_svcauth["Authentication service<br/>[authService.js]"]
  node_svcelective["Elective service<br/>[electiveService.js]"]
  node_svcpreferences["Preference service"]
  node_svcallocation["Allocation service"]
  node_svcreports["Report service<br/>[reportService.js]"]
  node_audit["Audit service<br/>[auditService.js]"]
end

subgraph group_persistence["Persistence and seed"]
  node_db[("SQLite database<br/>[database.js]")]
  node_dbseed["Database seed and reset<br/>[seed.js]"]
end

node_user(("Institutional user"))

node_user -->|"uses"| node_app
node_app -->|"renders"| node_login
node_app -->|"routes to"| node_student
node_app -->|"routes to"| node_catalogue
node_app -->|"routes to"| node_preferences
node_app -->|"routes to"| node_faculty
node_app -->|"routes to"| node_allocationadmin
node_app -->|"routes to"| node_result
node_app -->|"routes to"| node_reports
node_app -->|"routes to"| node_sysadmin
node_login -->|"authenticates with"| node_clientauth
node_student -->|"reads preferences"| node_clientprefs
node_student -->|"reads electives"| node_clientcatalogue
node_catalogue -->|"loads catalogue"| node_clientcatalogue
node_preferences -->|"submits choices"| node_clientprefs
node_preferences -->|"loads electives"| node_clientcatalogue
node_faculty -->|"manages courses"| node_clientcatalogue
node_allocationadmin -->|"runs allocation"| node_clientalloc
node_result -->|"loads outcome"| node_clientalloc
node_reports -->|"requests reports"| node_clientreports
node_sysadmin -->|"resets state"| node_storage
node_clientauth -->|"reads user data"| node_storage
node_clientauth -->|"creates session"| node_apiclient
node_clientcatalogue -->|"reads state"| node_storage
node_clientcatalogue -->|"validates courses"| node_validation
node_clientcatalogue -->|"persists courses"| node_apiclient
node_clientprefs -->|"validates choices"| node_validation
node_clientprefs -->|"reads state"| node_storage
node_clientalloc -->|"runs matcher"| node_engine
node_clientalloc -->|"checks readiness"| node_validation
node_clientalloc -->|"calls API"| node_apiclient
node_clientreports -->|"reads state"| node_storage
node_storage -->|"initializes from"| node_seeddata
node_storage -->|"syncs backend"| node_apiclient
node_apiclient -->|"sends HTTP requests"| node_router
node_router -->|"dispatches auth"| node_svcauth
node_router -->|"dispatches courses"| node_svcelective
node_router -->|"dispatches preferences"| node_svcpreferences
node_router -->|"dispatches allocation"| node_svcallocation
node_router -->|"dispatches reports"| node_svcreports
node_router -->|"dispatches audit"| node_audit
node_svcallocation -->|"runs matcher"| node_engine
node_svcallocation -->|"loads electives"| node_svcelective
node_svcallocation -->|"loads profiles"| node_svcauth
node_svcauth -->|"reads and writes"| node_db
node_svcelective -->|"reads and writes"| node_db
node_svcpreferences -->|"reads and writes"| node_db
node_svcallocation -->|"stores outcomes"| node_db

click node_app "https://github.com/adi02surana/elective-allocation-system/blob/main/src/App.jsx"
click node_login "https://github.com/adi02surana/elective-allocation-system/blob/main/src/pages/LoginPage.jsx"
click node_student "https://github.com/adi02surana/elective-allocation-system/blob/main/src/pages/StudentDashboard.jsx"
click node_catalogue "https://github.com/adi02surana/elective-allocation-system/blob/main/src/pages/ElectivesCatalogue.jsx"
click node_preferences "https://github.com/adi02surana/elective-allocation-system/blob/main/src/pages/PreferenceBuilder.jsx"
click node_faculty "https://github.com/adi02surana/elective-allocation-system/blob/main/src/pages/FacultyCourseManagement.jsx"
click node_allocationadmin "https://github.com/adi02surana/elective-allocation-system/blob/main/src/pages/AllocationAdmin.jsx"
click node_result "https://github.com/adi02surana/elective-allocation-system/blob/main/src/pages/StudentResultView.jsx"
click node_reports "https://github.com/adi02surana/elective-allocation-system/blob/main/src/pages/ReportsPage.jsx"
click node_sysadmin "https://github.com/adi02surana/elective-allocation-system/blob/main/src/pages/SysAdminPage.jsx"
click node_clientauth "https://github.com/adi02surana/elective-allocation-system/blob/main/src/services/authService.js"
click node_clientcatalogue "https://github.com/adi02surana/elective-allocation-system/blob/main/src/services/electiveService.js"
click node_clientprefs "https://github.com/adi02surana/elective-allocation-system/blob/main/src/services/preferenceService.js"
click node_clientalloc "https://github.com/adi02surana/elective-allocation-system/blob/main/src/services/allocationService.js"
click node_engine "https://github.com/adi02surana/elective-allocation-system/blob/main/src/services/allocationEngine.js"
click node_validation "https://github.com/adi02surana/elective-allocation-system/blob/main/src/services/validationService.js"
click node_clientreports "https://github.com/adi02surana/elective-allocation-system/blob/main/src/services/reportService.js"
click node_storage "https://github.com/adi02surana/elective-allocation-system/blob/main/src/services/storageService.js"
click node_seeddata "https://github.com/adi02surana/elective-allocation-system/blob/main/src/data/seedData.js"
click node_apiclient "https://github.com/adi02surana/elective-allocation-system/blob/main/src/services/apiClient.js"
click node_router "https://github.com/adi02surana/elective-allocation-system/blob/main/server/routes/apiRouter.js"
click node_svcauth "https://github.com/adi02surana/elective-allocation-system/blob/main/server/services/authService.js"
click node_svcelective "https://github.com/adi02surana/elective-allocation-system/blob/main/server/services/electiveService.js"
click node_svcpreferences "https://github.com/adi02surana/elective-allocation-system/blob/main/server/services/preferenceService.js"
click node_svcallocation "https://github.com/adi02surana/elective-allocation-system/blob/main/server/services/allocationService.js"
click node_svcreports "https://github.com/adi02surana/elective-allocation-system/blob/main/server/services/reportService.js"
click node_audit "https://github.com/adi02surana/elective-allocation-system/blob/main/server/services/auditService.js"
click node_db "https://github.com/adi02surana/elective-allocation-system/blob/main/server/db/database.js"
click node_dbseed "https://github.com/adi02surana/elective-allocation-system/blob/main/server/db/seed.js"

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_login,node_student,node_catalogue,node_preferences,node_faculty,node_allocationadmin,node_result,node_reports,node_sysadmin,node_user toneBlue
class node_clientauth,node_clientcatalogue,node_clientprefs,node_clientalloc,node_engine,node_validation,node_clientreports,node_storage,node_seeddata,node_apiclient toneAmber
class node_router,node_svcauth,node_svcelective,node_svcpreferences,node_svcallocation,node_svcreports,node_audit toneMint
class node_db,node_dbseed toneRose
```

## Components

### Role-based web app

- [App navigation](https://github.com/adi02surana/elective-allocation-system/blob/main/src/App.jsx): `src/App.jsx`
- [Login screen](https://github.com/adi02surana/elective-allocation-system/blob/main/src/pages/LoginPage.jsx): `src/pages/LoginPage.jsx`
- [Student dashboard](https://github.com/adi02surana/elective-allocation-system/blob/main/src/pages/StudentDashboard.jsx): `src/pages/StudentDashboard.jsx`
- [Elective catalogue](https://github.com/adi02surana/elective-allocation-system/blob/main/src/pages/ElectivesCatalogue.jsx): `src/pages/ElectivesCatalogue.jsx`
- [Preference builder](https://github.com/adi02surana/elective-allocation-system/blob/main/src/pages/PreferenceBuilder.jsx): `src/pages/PreferenceBuilder.jsx`
- [Course management](https://github.com/adi02surana/elective-allocation-system/blob/main/src/pages/FacultyCourseManagement.jsx): `src/pages/FacultyCourseManagement.jsx`
- [Allocation console](https://github.com/adi02surana/elective-allocation-system/blob/main/src/pages/AllocationAdmin.jsx): `src/pages/AllocationAdmin.jsx`
- [Student result](https://github.com/adi02surana/elective-allocation-system/blob/main/src/pages/StudentResultView.jsx): `src/pages/StudentResultView.jsx`
- [Analytics and CSV](https://github.com/adi02surana/elective-allocation-system/blob/main/src/pages/ReportsPage.jsx): `src/pages/ReportsPage.jsx`
- [System administration](https://github.com/adi02surana/elective-allocation-system/blob/main/src/pages/SysAdminPage.jsx): `src/pages/SysAdminPage.jsx`

### Client services

- [Client authentication](https://github.com/adi02surana/elective-allocation-system/blob/main/src/services/authService.js): `src/services/authService.js`
- [Client elective service](https://github.com/adi02surana/elective-allocation-system/blob/main/src/services/electiveService.js): `src/services/electiveService.js`
- [Client preference service](https://github.com/adi02surana/elective-allocation-system/blob/main/src/services/preferenceService.js): `src/services/preferenceService.js`
- [Client allocation service](https://github.com/adi02surana/elective-allocation-system/blob/main/src/services/allocationService.js): `src/services/allocationService.js`
- [Allocation engine](https://github.com/adi02surana/elective-allocation-system/blob/main/src/services/allocationEngine.js): `src/services/allocationEngine.js`
- [Preference validation](https://github.com/adi02surana/elective-allocation-system/blob/main/src/services/validationService.js): `src/services/validationService.js`
- [Client report service](https://github.com/adi02surana/elective-allocation-system/blob/main/src/services/reportService.js): `src/services/reportService.js`
- [Client state storage](https://github.com/adi02surana/elective-allocation-system/blob/main/src/services/storageService.js): `src/services/storageService.js`
- [Canonical seed data](https://github.com/adi02surana/elective-allocation-system/blob/main/src/data/seedData.js): `src/data/seedData.js`
- [HTTP API client](https://github.com/adi02surana/elective-allocation-system/blob/main/src/services/apiClient.js): `src/services/apiClient.js`

### API and domain services

- [REST API router](https://github.com/adi02surana/elective-allocation-system/blob/main/server/routes/apiRouter.js): `server/routes/apiRouter.js`
- [Authentication service](https://github.com/adi02surana/elective-allocation-system/blob/main/server/services/authService.js): `server/services/authService.js`
- [Elective service](https://github.com/adi02surana/elective-allocation-system/blob/main/server/services/electiveService.js): `server/services/electiveService.js`
- [Preference service](https://github.com/adi02surana/elective-allocation-system/blob/main/server/services/preferenceService.js): `server/services/preferenceService.js`
- [Allocation service](https://github.com/adi02surana/elective-allocation-system/blob/main/server/services/allocationService.js): `server/services/allocationService.js`
- [Report service](https://github.com/adi02surana/elective-allocation-system/blob/main/server/services/reportService.js): `server/services/reportService.js`
- [Audit service](https://github.com/adi02surana/elective-allocation-system/blob/main/server/services/auditService.js): `server/services/auditService.js`

### Persistence and seed

- [SQLite database](https://github.com/adi02surana/elective-allocation-system/blob/main/server/db/database.js): `server/db/database.js`
- [Database seed and reset](https://github.com/adi02surana/elective-allocation-system/blob/main/server/db/seed.js): `server/db/seed.js`

### Other components

- **Institutional user**

## Connections

- Institutional user → App navigation: uses (evidence: `README.md`)
- App navigation → Login screen: renders (evidence: `src/App.jsx`)
- App navigation → Student dashboard: routes to (evidence: `src/App.jsx`)
- App navigation → Elective catalogue: routes to (evidence: `src/App.jsx`)
- App navigation → Preference builder: routes to (evidence: `src/App.jsx`)
- App navigation → Course management: routes to (evidence: `src/App.jsx`)
- App navigation → Allocation console: routes to (evidence: `src/App.jsx`)
- App navigation → Student result: routes to (evidence: `src/App.jsx`)
- App navigation → Analytics and CSV: routes to (evidence: `src/App.jsx`)
- App navigation → System administration: routes to (evidence: `src/App.jsx`)
- Login screen → Client authentication: authenticates with (evidence: `src/pages/LoginPage.jsx`)
- Student dashboard → Client preference service: reads preferences (evidence: `src/pages/StudentDashboard.jsx`)
- Student dashboard → Client elective service: reads electives (evidence: `src/pages/StudentDashboard.jsx`)
- Elective catalogue → Client elective service: loads catalogue (evidence: `src/pages/ElectivesCatalogue.jsx`)
- Preference builder → Client preference service: submits choices (evidence: `src/pages/PreferenceBuilder.jsx`)
- Preference builder → Client elective service: loads electives (evidence: `src/pages/PreferenceBuilder.jsx`)
- Course management → Client elective service: manages courses (evidence: `src/pages/FacultyCourseManagement.jsx`)
- Allocation console → Client allocation service: runs allocation (evidence: `src/pages/AllocationAdmin.jsx`)
- Student result → Client allocation service: loads outcome (evidence: `src/pages/StudentResultView.jsx`)
- Analytics and CSV → Client report service: requests reports (evidence: `src/pages/ReportsPage.jsx`)
- System administration → Client state storage: resets state (evidence: `src/pages/SysAdminPage.jsx`)
- Client authentication → Client state storage: reads user data (evidence: `src/services/authService.js`)
- Client authentication → HTTP API client: creates session (evidence: `src/services/authService.js`)
- Client elective service → Client state storage: reads state (evidence: `src/services/electiveService.js`)
- Client elective service → Preference validation: validates courses (evidence: `src/services/electiveService.js`)
- Client elective service → HTTP API client: persists courses (evidence: `src/services/electiveService.js`)
- Client preference service → Preference validation: validates choices (evidence: `src/services/preferenceService.js`)
- Client preference service → Client state storage: reads state (evidence: `src/services/preferenceService.js`)
- Client allocation service → Allocation engine: runs matcher (evidence: `src/services/allocationService.js`)
- Client allocation service → Preference validation: checks readiness (evidence: `src/services/allocationService.js`)
- Client allocation service → HTTP API client: calls API (evidence: `src/services/allocationService.js`)
- Client report service → Client state storage: reads state (evidence: `src/services/reportService.js`)
- Client state storage → Canonical seed data: initializes from (evidence: `src/services/storageService.js`)
- Client state storage → HTTP API client: syncs backend (evidence: `src/services/storageService.js`)
- HTTP API client → REST API router: sends HTTP requests (evidence: `README.md`)
- REST API router → Authentication service: dispatches auth (evidence: `server/routes/apiRouter.js`)
- REST API router → Elective service: dispatches courses (evidence: `server/routes/apiRouter.js`)
- REST API router → Preference service: dispatches preferences (evidence: `server/routes/apiRouter.js`)
- REST API router → Allocation service: dispatches allocation (evidence: `server/routes/apiRouter.js`)
- REST API router → Report service: dispatches reports (evidence: `server/routes/apiRouter.js`)
- REST API router → Audit service: dispatches audit (evidence: `server/routes/apiRouter.js`)
- Allocation service → Allocation engine: runs matcher (evidence: `server/services/allocationService.js`)
- Allocation service → Elective service: loads electives (evidence: `server/services/allocationService.js`)
- Allocation service → Authentication service: loads profiles (evidence: `server/services/allocationService.js`)
- Authentication service → SQLite database: reads and writes (evidence: `server/services/authService.js`)
- Elective service → SQLite database: reads and writes (evidence: `server/services/electiveService.js`)
- Preference service → SQLite database: reads and writes (evidence: `server/services/preferenceService.js`)
- Allocation service → SQLite database: stores outcomes (evidence: `server/services/allocationService.js`)
