# reshist/homs-app architecture

> Architecture diagram of the GitHub repository reshist/homs-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/reshist/homs-app
- Repository: https://github.com/reshist/homs-app

## Overview

#### Purpose and Runtime
HOMS is a Flutter/Dart mobile client for hostel out-pass requests and authority review. It is intended for Android and depends on a PHP API backed by MySQL; neither backend code nor database schema is present here. The application entry point is `main.dart`.

#### Role-Based Access Boundary
Login is split by user role—student, CA, HOD, VP, and warden—indicating role-specific authentication and navigation rather than a shared generic portal. Primary screens are `screens/login/student.dart`, `screens/login/warden.dart`, and `screens/login/hod.dart`; equivalent CA and VP entry screens exist alongside them.

#### Student Request Lifecycle
Students initiate and track their own passes through the student area. `screens/student/pass-apply.dart` is the request-submission boundary, while `screens/student/pass-history.dart` presents prior request outcomes. `screens/student/profile.dart` represents the student account/profile surface. README notes these Android capabilities remain under development despite being functional in the referenced web application.

#### Authority Workflow and State Queues
Passes move through explicit status partitions: pending, approved, and declined. Each authority role has separate views in `screens/pending-pass/warden.dart`, `screens/approved-pass/hod.dart`, and `screens/declined-pass/vp.dart` (with parallel CA/HOD/VP/warden files). This layout makes approval/rejection a role-scoped workflow, with status changes persisted through the PHP/MySQL backend and reflected back to student history/status views.

#### Role Dashboards and Student Review
Authority landing areas are role-specific dashboards: `screens/dashboard/ca.dart`, `screens/dashboard/hod.dart`, and `screens/dashboard/warden.dart`. Detailed student inspection is likewise role-partitioned in `screens/student-details/ca.dart`, `screens/student-details/vp.dart`, and `screens/student-details/warden.dart`. The likely control flow is login → role dashboard → status queue → student/pass detail → approve or decline.

#### Warden Administration
The warden area owns management-oriented capabilities beyond reviewing requests: `screens/warden/add-pass.dart`, `screens/warden/add-department.dart`, and `screens/warden/add-student.dart`. Supporting listing/management screens, `screens/warden/pass.dart` and `screens/warden/department.dart`, imply warden control over pass types and department/student reference data consumed by pass application and review flows.

#### Integration Boundary
All mobile screens are UI-layer Dart files under `screens/`; no in-repository API client, state-management layer, backend implementation, or notification provider is visible in the supplied tree. The material external boundary is therefore Flutter client calls to the PHP API, which owns authentication, request status, approval decisions, and MySQL persistence. “Real-time status updates” are a product requirement, but the implementation mechanism is not evidenced here.

Main entry points: [`screens/dashboard/ca.dart`](https://github.com/reshist/homs-app/blob/main/screens/dashboard/ca.dart) (Role dashboards), [`screens/login/student.dart`](https://github.com/reshist/homs-app/blob/main/screens/login/student.dart) (Role login screens), [`screens/student/pass-apply.dart`](https://github.com/reshist/homs-app/blob/main/screens/student/pass-apply.dart) (Pass application), [`screens/student/pass-history.dart`](https://github.com/reshist/homs-app/blob/main/screens/student/pass-history.dart) (Pass history)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Flutter mobile client"]
  node_entry(("App entry<br/>Flutter bootstrap<br/>[main.dart]"))
  node_role_login["Role login screens<br/>authentication UI<br/>[student.dart]"]
end

subgraph group_student["Student flow"]
  node_student_apply["Pass application<br/>student UI<br/>[pass-apply.dart]"]
  node_student_history["Pass history<br/>student UI<br/>[pass-history.dart]"]
  node_student_profile["Student profile<br/>student UI<br/>[profile.dart]"]
end

subgraph group_authority["Authority workflow"]
  node_dashboards["Role dashboards<br/>authority UI<br/>[ca.dart]"]
  node_pending_queue["Pending pass queue<br/>workflow queue UI<br/>[warden.dart]"]
  node_approved_queue["Approved pass queue<br/>workflow queue UI<br/>[hod.dart]"]
  node_declined_queue["Declined pass queue<br/>workflow queue UI<br/>[vp.dart]"]
  node_student_review["Student/pass review<br/>authority detail UI<br/>[ca.dart]"]
  node_warden_pass_admin["Pass type management<br/>warden admin UI<br/>[pass.dart]"]
  node_warden_department_admin["Department management<br/>warden admin UI<br/>[department.dart]"]
  node_warden_student_admin["Student administration<br/>warden admin UI<br/>[add-student.dart]"]
end

subgraph group_backend["External backend"]
  node_php_api{{"PHP API<br/>external service"}}
  node_mysql[("MySQL<br/>external database")]
end

node_entry -->|"starts"| node_role_login
node_role_login -->|"student access"| node_student_apply
node_role_login -->|"authority access"| node_dashboards
node_student_apply -->|"submits request"| node_php_api
node_student_history -->|"loads status"| node_php_api
node_student_profile -->|"loads account"| node_php_api
node_dashboards -->|"opens queue"| node_pending_queue
node_pending_queue -->|"inspects request"| node_student_review
node_student_review -->|"approve or decline"| node_php_api
node_php_api -->|"approved state"| node_approved_queue
node_php_api -->|"declined state"| node_declined_queue
node_php_api -->|"updated outcome"| node_student_history
node_dashboards -->|"warden management"| node_warden_pass_admin
node_dashboards -->|"warden management"| node_warden_department_admin
node_dashboards -->|"warden management"| node_warden_student_admin
node_warden_pass_admin -->|"manages pass types"| node_php_api
node_warden_department_admin -->|"manages departments"| node_php_api
node_warden_student_admin -->|"manages students"| node_php_api
node_php_api -->|"persists state"| node_mysql

click node_entry "https://github.com/reshist/homs-app/blob/main/main.dart"
click node_role_login "https://github.com/reshist/homs-app/blob/main/screens/login/student.dart"
click node_student_apply "https://github.com/reshist/homs-app/blob/main/screens/student/pass-apply.dart"
click node_student_history "https://github.com/reshist/homs-app/blob/main/screens/student/pass-history.dart"
click node_student_profile "https://github.com/reshist/homs-app/blob/main/screens/student/profile.dart"
click node_dashboards "https://github.com/reshist/homs-app/blob/main/screens/dashboard/ca.dart"
click node_pending_queue "https://github.com/reshist/homs-app/blob/main/screens/pending-pass/warden.dart"
click node_approved_queue "https://github.com/reshist/homs-app/blob/main/screens/approved-pass/hod.dart"
click node_declined_queue "https://github.com/reshist/homs-app/blob/main/screens/declined-pass/vp.dart"
click node_student_review "https://github.com/reshist/homs-app/blob/main/screens/student-details/ca.dart"
click node_warden_pass_admin "https://github.com/reshist/homs-app/blob/main/screens/warden/pass.dart"
click node_warden_department_admin "https://github.com/reshist/homs-app/blob/main/screens/warden/department.dart"
click node_warden_student_admin "https://github.com/reshist/homs-app/blob/main/screens/warden/add-student.dart"

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_entry,node_role_login toneBlue
class node_student_apply,node_student_history,node_student_profile toneAmber
class node_dashboards,node_pending_queue,node_approved_queue,node_declined_queue,node_student_review,node_warden_pass_admin,node_warden_department_admin,node_warden_student_admin toneMint
class node_php_api,node_mysql toneRose
```

## Components

### Flutter mobile client

- [App entry](https://github.com/reshist/homs-app/blob/main/main.dart): Flutter bootstrap · `main.dart`
- [Role login screens](https://github.com/reshist/homs-app/blob/main/screens/login/student.dart): authentication UI · Separate entry points exist for student, CA, HOD, VP, and warden. · `screens/login/student.dart`

### Student flow

- [Pass application](https://github.com/reshist/homs-app/blob/main/screens/student/pass-apply.dart): student UI · `screens/student/pass-apply.dart`
- [Pass history](https://github.com/reshist/homs-app/blob/main/screens/student/pass-history.dart): student UI · Shows request outcomes and status. · `screens/student/pass-history.dart`
- [Student profile](https://github.com/reshist/homs-app/blob/main/screens/student/profile.dart): student UI · `screens/student/profile.dart`

### Authority workflow

- [Role dashboards](https://github.com/reshist/homs-app/blob/main/screens/dashboard/ca.dart): authority UI · Role-specific landing areas for CA, HOD, and warden. · `screens/dashboard/ca.dart`
- [Pending pass queue](https://github.com/reshist/homs-app/blob/main/screens/pending-pass/warden.dart): workflow queue UI · Role-scoped requests awaiting review. · `screens/pending-pass/warden.dart`
- [Approved pass queue](https://github.com/reshist/homs-app/blob/main/screens/approved-pass/hod.dart): workflow queue UI · `screens/approved-pass/hod.dart`
- [Declined pass queue](https://github.com/reshist/homs-app/blob/main/screens/declined-pass/vp.dart): workflow queue UI · `screens/declined-pass/vp.dart`
- [Student/pass review](https://github.com/reshist/homs-app/blob/main/screens/student-details/ca.dart): authority detail UI · Role-partitioned student inspection before a decision. · `screens/student-details/ca.dart`
- [Pass type management](https://github.com/reshist/homs-app/blob/main/screens/warden/pass.dart): warden admin UI · `screens/warden/pass.dart`
- [Department management](https://github.com/reshist/homs-app/blob/main/screens/warden/department.dart): warden admin UI · `screens/warden/department.dart`
- [Student administration](https://github.com/reshist/homs-app/blob/main/screens/warden/add-student.dart): warden admin UI · `screens/warden/add-student.dart`

### External backend

- **PHP API**: external service · Owns authentication, request status, and approval decisions.
- **MySQL**: external database · Persists users, reference data, and pass workflow state.

## Connections

- App entry → Role login screens: starts
- Role login screens → Pass application: student access
- Role login screens → Role dashboards: authority access
- Pass application → PHP API: submits request
- Pass history → PHP API: loads status
- Student profile → PHP API: loads account
- Role dashboards → Pending pass queue: opens queue
- Pending pass queue → Student/pass review: inspects request
- Student/pass review → PHP API: approve or decline
- PHP API → Approved pass queue: approved state
- PHP API → Declined pass queue: declined state
- PHP API → Pass history: updated outcome
- Role dashboards → Pass type management: warden management
- Role dashboards → Department management: warden management
- Role dashboards → Student administration: warden management
- Pass type management → PHP API: manages pass types
- Department management → PHP API: manages departments
- Student administration → PHP API: manages students
- PHP API → MySQL: persists state