# nadir-ashraf/hms-nexus architecture

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

- Interactive diagram: https://gitdiagram.com/nadir-ashraf/hms-nexus
- Repository: https://github.com/nadir-ashraf/hms-nexus

## Overview

HMS Nexus is a role-based desktop hostel-management application. Users enter through the CustomTkinter window, authenticate, and navigate to role-specific views; those views invoke a centralized database service that applies operations to SQLAlchemy models persisted in SQLite. The product spans student records, hostel inventory and bed allocation, fees, attendance, complaints, notices, visitors, and leave requests. The graph follows documented navigation and sampled view-to-service calls; several feature views are represented from the source index and README, so their internal call details are not inferred.

Main entry points: [`app/gui/main_window.py`](https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/main_window.py) (App window), [`app/db_service.py`](https://github.com/nadir-ashraf/hms-nexus/blob/main/app/db_service.py) (Database service), [`app/gui/views/notices_view.py`](https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/notices_view.py) (Notice board), [`app/__init__.py`](https://github.com/nadir-ashraf/hms-nexus/blob/main/app/__init__.py) (App and DB setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop interface"]
  node_window["App window<br/>[main_window.py]"]
  node_theme["Theme tokens<br/>[theme.py]"]
  node_components["UI components<br/>[components.py]"]
end

subgraph group_people["People and access"]
  node_login["Role login<br/>[login_view.py]"]
  node_admin_dash["Admin dashboard"]
  node_student_dash["Student dashboard"]
  node_students["Student directory<br/>[students_view.py]"]
end

subgraph group_housing["Housing and finance"]
  node_hostels["Hostels and rooms"]
  node_allocations["Bed allocation"]
  node_fees["Fee management<br/>[fees_view.py]"]
end

subgraph group_operations["Hostel operations"]
  node_warden_dash["Warden dashboard"]
  node_attendance["Attendance<br/>[attendance_view.py]"]
  node_complaints["Complaints<br/>[complaints_view.py]"]
  node_notices["Notice board<br/>[notices_view.py]"]
  node_visitors["Visitor gate log<br/>[visitors_view.py]"]
  node_leaves["Leave requests<br/>[leaves_view.py]"]
end

subgraph group_data["Persistence layer"]
  node_service["Database service<br/>[db_service.py]"]
  node_models["Domain models<br/>[models.py]"]
  node_app_config["App and DB setup<br/>[__init__.py]"]
  node_sqlite[("SQLite database<br/>[hms.db]")]
end

node_user(("Hostel user"))

node_user -->|"uses"| node_window
node_window -->|"shows"| node_login
node_window -->|"routes to"| node_admin_dash
node_window -->|"routes to"| node_warden_dash
node_window -->|"routes to"| node_student_dash
node_window -->|"routes to"| node_students
node_window -->|"routes to"| node_hostels
node_window -->|"routes to"| node_allocations
node_window -->|"routes to"| node_fees
node_window -->|"routes to"| node_attendance
node_window -->|"routes to"| node_complaints
node_window -->|"routes to"| node_notices
node_window -->|"routes to"| node_visitors
node_window -->|"routes to"| node_leaves
node_window -->|"styles with"| node_theme
node_window -->|"uses"| node_components
node_login -->|"authenticates via"| node_service
node_students -->|"queries and updates"| node_service
node_hostels -->|"queries and updates"| node_service
node_allocations -->|"allocates beds via"| node_service
node_fees -->|"manages invoices via"| node_service
node_attendance -->|"records via"| node_service
node_complaints -->|"manages via"| node_service
node_notices -->|"publishes via"| node_service
node_visitors -->|"logs via"| node_service
node_leaves -->|"reviews via"| node_service
node_warden_dash -->|"publishes through"| node_notices
node_service -->|"queries and mutates"| node_models
node_app_config -->|"configures ORM"| node_models
node_app_config -->|"configures SQLite"| node_sqlite
node_service -.->|"persists records"| node_sqlite

click node_window "https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/main_window.py"
click node_theme "https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/theme.py"
click node_components "https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/components.py"
click node_login "https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/login_view.py"
click node_admin_dash "https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/admin_dashboard_view.py"
click node_warden_dash "https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/warden_dashboard_view.py"
click node_student_dash "https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/student_dashboard_view.py"
click node_students "https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/students_view.py"
click node_hostels "https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/hostels_rooms_view.py"
click node_allocations "https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/allocations_view.py"
click node_fees "https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/fees_view.py"
click node_attendance "https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/attendance_view.py"
click node_complaints "https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/complaints_view.py"
click node_notices "https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/notices_view.py"
click node_visitors "https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/visitors_view.py"
click node_leaves "https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/leaves_view.py"
click node_service "https://github.com/nadir-ashraf/hms-nexus/blob/main/app/db_service.py"
click node_models "https://github.com/nadir-ashraf/hms-nexus/blob/main/app/models.py"
click node_app_config "https://github.com/nadir-ashraf/hms-nexus/blob/main/app/__init__.py"
click node_sqlite "https://github.com/nadir-ashraf/hms-nexus/blob/main/instance/hms.db"

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_window,node_theme,node_components,node_user toneBlue
class node_login,node_admin_dash,node_student_dash,node_students toneAmber
class node_hostels,node_allocations,node_fees toneMint
class node_warden_dash,node_attendance,node_complaints,node_notices,node_visitors,node_leaves toneRose
class node_service,node_models,node_app_config,node_sqlite toneIndigo
```

## Components

### Desktop interface

- [App window](https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/main_window.py): `app/gui/main_window.py`
- [Theme tokens](https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/theme.py): `app/gui/theme.py`
- [UI components](https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/components.py): `app/gui/components.py`

### People and access

- [Role login](https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/login_view.py): `app/gui/views/login_view.py`
- [Admin dashboard](https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/admin_dashboard_view.py): `app/gui/views/admin_dashboard_view.py`
- [Student dashboard](https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/student_dashboard_view.py): `app/gui/views/student_dashboard_view.py`
- [Student directory](https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/students_view.py): `app/gui/views/students_view.py`

### Housing and finance

- [Hostels and rooms](https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/hostels_rooms_view.py): `app/gui/views/hostels_rooms_view.py`
- [Bed allocation](https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/allocations_view.py): `app/gui/views/allocations_view.py`
- [Fee management](https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/fees_view.py): `app/gui/views/fees_view.py`

### Hostel operations

- [Warden dashboard](https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/warden_dashboard_view.py): `app/gui/views/warden_dashboard_view.py`
- [Attendance](https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/attendance_view.py): `app/gui/views/attendance_view.py`
- [Complaints](https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/complaints_view.py): `app/gui/views/complaints_view.py`
- [Notice board](https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/notices_view.py): `app/gui/views/notices_view.py`
- [Visitor gate log](https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/visitors_view.py): `app/gui/views/visitors_view.py`
- [Leave requests](https://github.com/nadir-ashraf/hms-nexus/blob/main/app/gui/views/leaves_view.py): `app/gui/views/leaves_view.py`

### Persistence layer

- [Database service](https://github.com/nadir-ashraf/hms-nexus/blob/main/app/db_service.py): `app/db_service.py`
- [Domain models](https://github.com/nadir-ashraf/hms-nexus/blob/main/app/models.py): `app/models.py`
- [App and DB setup](https://github.com/nadir-ashraf/hms-nexus/blob/main/app/__init__.py): `app/__init__.py`
- [SQLite database](https://github.com/nadir-ashraf/hms-nexus/blob/main/instance/hms.db): `instance/hms.db`

### Other components

- **Hostel user**

## Connections

- Hostel user → App window: uses (evidence: `README.md`)
- App window → Role login: shows (evidence: `app/gui/main_window.py`)
- App window → Admin dashboard: routes to (evidence: `app/gui/main_window.py`)
- App window → Warden dashboard: routes to (evidence: `app/gui/main_window.py`)
- App window → Student dashboard: routes to (evidence: `app/gui/main_window.py`)
- App window → Student directory: routes to (evidence: `app/gui/main_window.py`)
- App window → Hostels and rooms: routes to (evidence: `app/gui/main_window.py`)
- App window → Bed allocation: routes to (evidence: `app/gui/main_window.py`)
- App window → Fee management: routes to (evidence: `app/gui/main_window.py`)
- App window → Attendance: routes to (evidence: `app/gui/main_window.py`)
- App window → Complaints: routes to (evidence: `app/gui/main_window.py`)
- App window → Notice board: routes to (evidence: `app/gui/main_window.py`)
- App window → Visitor gate log: routes to (evidence: `app/gui/main_window.py`)
- App window → Leave requests: routes to (evidence: `app/gui/main_window.py`)
- App window → Theme tokens: styles with (evidence: `app/gui/main_window.py`)
- App window → UI components: uses (evidence: `app/gui/main_window.py`)
- Role login → Database service: authenticates via (evidence: `app/gui/views/login_view.py`)
- Student directory → Database service: queries and updates (evidence: `app/gui/views/students_view.py`)
- Hostels and rooms → Database service: queries and updates (evidence: `app/gui/views/hostels_rooms_view.py`)
- Bed allocation → Database service: allocates beds via (evidence: `app/gui/views/allocations_view.py`)
- Fee management → Database service: manages invoices via (evidence: `app/gui/views/fees_view.py`)
- Attendance → Database service: records via (evidence: `app/gui/views/attendance_view.py`)
- Complaints → Database service: manages via (evidence: `app/gui/views/complaints_view.py`)
- Notice board → Database service: publishes via (evidence: `app/gui/views/notices_view.py`)
- Visitor gate log → Database service: logs via (evidence: `app/gui/views/visitors_view.py`)
- Leave requests → Database service: reviews via (evidence: `app/gui/views/leaves_view.py`)
- Warden dashboard → Notice board: publishes through (evidence: `app/gui/views/warden_dashboard_view.py`)
- Database service → Domain models: queries and mutates (evidence: `app/db_service.py`)
- App and DB setup → Domain models: configures ORM (evidence: `app/__init__.py`)
- App and DB setup → SQLite database: configures SQLite (evidence: `app/__init__.py`)
- Database service → SQLite database: persists records
