# sanhith2117s/garuda-m architecture

> Architecture diagram of the GitHub repository sanhith2117s/garuda-m, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sanhith2117s/garuda-m
- Repository: https://github.com/sanhith2117s/garuda-m

## Overview

Garuda is a role-based campus student leave, pass, and gate-management system. Users sign in through the web portal; administrators, HODs, mentors, and security staff access role-specific workflows, including pass issuance and administration, student lookup, and gate scanning. The backend exposes these domains through FastAPI routers, persists their records in a relational database, and runs scheduled pass-expiry and semester-promotion tasks. The tree and sampled code support the application entry points and broad domain areas, but not detailed endpoint wiring for unsampled routers; those links are kept at the router/domain level.

Main entry points: [`backend/main.py`](https://github.com/sanhith2117s/garuda-m/blob/main/backend/main.py) (API application), [`backend/db/database.py`](https://github.com/sanhith2117s/garuda-m/blob/main/backend/db/database.py) (Database sessions), [`frontend/src/App.tsx`](https://github.com/sanhith2117s/garuda-m/blob/main/frontend/src/App.tsx) (Role portals), [`backend/api/auth.py`](https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/auth.py) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web portals"]
  node_app["Role portals<br/>[App.tsx]"]
  node_login["Sign in<br/>[LoginPage.tsx]"]
  node_adminui["Admin console<br/>[AdminDashboard.tsx]"]
  node_hodui["HOD portal<br/>[HODDashboard.tsx]"]
  node_mentorui["Mentor portal"]
  node_securityui["Gate scanner<br/>[SecurityApp.tsx]"]
  node_studentui["Student portal<br/>[ScannerApp.tsx]"]
end

subgraph group_api["API domains"]
  node_authapi["Authentication<br/>[auth.py]"]
  node_gateapi["Gate operations<br/>[gate.py]"]
  node_studentapi["Student operations<br/>[student.py]"]
  node_passapi["Pass management<br/>[lunch.py]"]
  node_customapi["Custom passes<br/>[custom_pass.py]"]
  node_lateapi["Latecomers<br/>[latecomers.py]"]
  node_bulkapi["Bulk passes<br/>[bulk.py]"]
  node_directoryapi["Student directory<br/>[directory.py]"]
  node_onboardapi["Student onboarding<br/>[onboarding.py]"]
  node_semesterapi["Semester management<br/>[semester.py]"]
  node_adminapi["Campus administration<br/>[colleges.py]"]
  node_staffapi["Staff assignments<br/>[mentors.py]"]
  node_hodapi["HOD operations<br/>[hod.py]"]
  node_announceapi["Announcements<br/>[announcements.py]"]
  node_auditapi["Audit records<br/>[audit.py]"]
  node_exportapi["Data exports<br/>[exports.py]"]
  node_backend["API application<br/>[main.py]"]
end

subgraph group_data["Persistence"]
  node_dbsession["Database sessions<br/>[database.py]"]
  node_models["Domain records<br/>[models.py]"]
  node_database[("Relational database")]
end

subgraph group_ops["Lifecycle services"]
  node_tasks["Scheduled lifecycle<br/>[tasks.py]"]
end

node_actor(("Campus users"))

node_actor -->|"uses"| node_app
node_app -->|"routes"| node_login
node_app -->|"routes"| node_adminui
node_app -->|"routes"| node_hodui
node_app -->|"routes"| node_mentorui
node_app -->|"routes"| node_securityui
node_app -->|"routes"| node_studentui
node_login -->|"submits credentials"| node_authapi
node_adminui -->|"calls API"| node_backend
node_hodui -->|"calls API"| node_backend
node_mentorui -->|"calls API"| node_backend
node_securityui -->|"scans passes"| node_gateapi
node_studentui -->|"requests student data"| node_studentapi
node_backend -->|"registers routes"| node_authapi
node_backend -->|"registers routes"| node_gateapi
node_backend -->|"registers routes"| node_studentapi
node_backend -->|"registers routes"| node_passapi
node_backend -->|"registers routes"| node_customapi
node_backend -->|"registers routes"| node_lateapi
node_backend -->|"registers routes"| node_bulkapi
node_backend -->|"registers routes"| node_directoryapi
node_backend -->|"registers routes"| node_onboardapi
node_backend -->|"registers routes"| node_semesterapi
node_backend -->|"registers routes"| node_adminapi
node_backend -->|"registers routes"| node_staffapi
node_backend -->|"registers routes"| node_hodapi
node_backend -->|"registers routes"| node_announceapi
node_backend -->|"registers routes"| node_auditapi
node_backend -->|"registers routes"| node_exportapi
node_authapi -->|"queries and updates"| node_dbsession
node_gateapi -->|"uses sessions"| node_dbsession
node_studentapi -->|"uses sessions"| node_dbsession
node_passapi -->|"uses sessions"| node_dbsession
node_customapi -->|"uses sessions"| node_dbsession
node_dbsession -->|"maps entities"| node_models
node_dbsession -->|"reads and writes"| node_database
node_backend -->|"starts tasks"| node_tasks
node_tasks -->|"updates records"| node_dbsession

click node_app "https://github.com/sanhith2117s/garuda-m/blob/main/frontend/src/App.tsx"
click node_login "https://github.com/sanhith2117s/garuda-m/blob/main/frontend/src/pages/LoginPage.tsx"
click node_adminui "https://github.com/sanhith2117s/garuda-m/blob/main/frontend/src/pages/AdminDashboard.tsx"
click node_hodui "https://github.com/sanhith2117s/garuda-m/blob/main/frontend/src/pages/hod/HODDashboard.tsx"
click node_mentorui "https://github.com/sanhith2117s/garuda-m/blob/main/frontend/src/pages/mentor/MentorDashboard.tsx"
click node_securityui "https://github.com/sanhith2117s/garuda-m/blob/main/frontend/src/pages/security/SecurityApp.tsx"
click node_studentui "https://github.com/sanhith2117s/garuda-m/blob/main/frontend/src/pages/ScannerApp.tsx"
click node_authapi "https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/auth.py"
click node_gateapi "https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/gate.py"
click node_studentapi "https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/student.py"
click node_passapi "https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/lunch.py"
click node_customapi "https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/custom_pass.py"
click node_lateapi "https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/latecomers.py"
click node_bulkapi "https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/bulk.py"
click node_directoryapi "https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/directory.py"
click node_onboardapi "https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/onboarding.py"
click node_semesterapi "https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/semester.py"
click node_adminapi "https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/colleges.py"
click node_staffapi "https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/mentors.py"
click node_hodapi "https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/hod.py"
click node_announceapi "https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/announcements.py"
click node_auditapi "https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/audit.py"
click node_exportapi "https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/exports.py"
click node_backend "https://github.com/sanhith2117s/garuda-m/blob/main/backend/main.py"
click node_dbsession "https://github.com/sanhith2117s/garuda-m/blob/main/backend/db/database.py"
click node_models "https://github.com/sanhith2117s/garuda-m/blob/main/backend/db/models.py"
click node_tasks "https://github.com/sanhith2117s/garuda-m/blob/main/backend/core/tasks.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_login,node_adminui,node_hodui,node_mentorui,node_securityui,node_studentui,node_actor toneBlue
class node_authapi,node_gateapi,node_studentapi,node_passapi,node_customapi,node_lateapi,node_bulkapi,node_directoryapi,node_onboardapi,node_semesterapi,node_adminapi,node_staffapi,node_hodapi,node_announceapi,node_auditapi,node_exportapi,node_backend toneAmber
class node_dbsession,node_models,node_database toneMint
class node_tasks toneRose
```

## Components

### Web portals

- [Role portals](https://github.com/sanhith2117s/garuda-m/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Sign in](https://github.com/sanhith2117s/garuda-m/blob/main/frontend/src/pages/LoginPage.tsx): `frontend/src/pages/LoginPage.tsx`
- [Admin console](https://github.com/sanhith2117s/garuda-m/blob/main/frontend/src/pages/AdminDashboard.tsx): `frontend/src/pages/AdminDashboard.tsx`
- [HOD portal](https://github.com/sanhith2117s/garuda-m/blob/main/frontend/src/pages/hod/HODDashboard.tsx): `frontend/src/pages/hod/HODDashboard.tsx`
- [Mentor portal](https://github.com/sanhith2117s/garuda-m/blob/main/frontend/src/pages/mentor/MentorDashboard.tsx): `frontend/src/pages/mentor/MentorDashboard.tsx`
- [Gate scanner](https://github.com/sanhith2117s/garuda-m/blob/main/frontend/src/pages/security/SecurityApp.tsx): `frontend/src/pages/security/SecurityApp.tsx`
- [Student portal](https://github.com/sanhith2117s/garuda-m/blob/main/frontend/src/pages/ScannerApp.tsx): `frontend/src/pages/ScannerApp.tsx`

### API domains

- [Authentication](https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/auth.py): `backend/api/auth.py`
- [Gate operations](https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/gate.py): `backend/api/gate.py`
- [Student operations](https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/student.py): `backend/api/student.py`
- [Pass management](https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/lunch.py): `backend/api/lunch.py`
- [Custom passes](https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/custom_pass.py): `backend/api/custom_pass.py`
- [Latecomers](https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/latecomers.py): `backend/api/latecomers.py`
- [Bulk passes](https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/bulk.py): `backend/api/bulk.py`
- [Student directory](https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/directory.py): `backend/api/directory.py`
- [Student onboarding](https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/onboarding.py): `backend/api/onboarding.py`
- [Semester management](https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/semester.py): `backend/api/semester.py`
- [Campus administration](https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/colleges.py): `backend/api/colleges.py`
- [Staff assignments](https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/mentors.py): `backend/api/mentors.py`
- [HOD operations](https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/hod.py): `backend/api/hod.py`
- [Announcements](https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/announcements.py): `backend/api/announcements.py`
- [Audit records](https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/audit.py): `backend/api/audit.py`
- [Data exports](https://github.com/sanhith2117s/garuda-m/blob/main/backend/api/exports.py): `backend/api/exports.py`
- [API application](https://github.com/sanhith2117s/garuda-m/blob/main/backend/main.py): `backend/main.py`

### Persistence

- [Database sessions](https://github.com/sanhith2117s/garuda-m/blob/main/backend/db/database.py): `backend/db/database.py`
- [Domain records](https://github.com/sanhith2117s/garuda-m/blob/main/backend/db/models.py): `backend/db/models.py`
- **Relational database**

### Lifecycle services

- [Scheduled lifecycle](https://github.com/sanhith2117s/garuda-m/blob/main/backend/core/tasks.py): `backend/core/tasks.py`

### Other components

- **Campus users**

## Connections

- Campus users → Role portals: uses
- Role portals → Sign in: routes
- Role portals → Admin console: routes
- Role portals → HOD portal: routes
- Role portals → Mentor portal: routes
- Role portals → Gate scanner: routes
- Role portals → Student portal: routes
- Sign in → Authentication: submits credentials
- Admin console → API application: calls API
- HOD portal → API application: calls API
- Mentor portal → API application: calls API
- Gate scanner → Gate operations: scans passes
- Student portal → Student operations: requests student data
- API application → Authentication: registers routes
- API application → Gate operations: registers routes
- API application → Student operations: registers routes
- API application → Pass management: registers routes
- API application → Custom passes: registers routes
- API application → Latecomers: registers routes
- API application → Bulk passes: registers routes
- API application → Student directory: registers routes
- API application → Student onboarding: registers routes
- API application → Semester management: registers routes
- API application → Campus administration: registers routes
- API application → Staff assignments: registers routes
- API application → HOD operations: registers routes
- API application → Announcements: registers routes
- API application → Audit records: registers routes
- API application → Data exports: registers routes
- Authentication → Database sessions: queries and updates
- Gate operations → Database sessions: uses sessions
- Student operations → Database sessions: uses sessions
- Pass management → Database sessions: uses sessions
- Custom passes → Database sessions: uses sessions
- Database sessions → Domain records: maps entities
- Database sessions → Relational database: reads and writes
- API application → Scheduled lifecycle: starts tasks
- Scheduled lifecycle → Database sessions: updates records