# fireproof-zarry/hostel-complaints-ticketing-system architecture

> Architecture diagram of the GitHub repository fireproof-zarry/hostel-complaints-ticketing-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fireproof-zarry/hostel-complaints-ticketing-system
- Repository: https://github.com/fireproof-zarry/hostel-complaints-ticketing-system

## Overview

HostelFix is a student and administrator portal for reporting and managing hostel complaints. Users sign in with Google; the frontend verifies the credential with the backend and routes by role. Students can file and track complaints, while administrators review, filter, assign, and update them. The README documents Google-verified account rules and a Supabase-backed backend. Backend internals are represented by their source paths from the tree; their call relationships are not verified in the provided excerpts.

Main entry points: [`frontend/src/pages/Login.jsx`](https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/frontend/src/pages/Login.jsx) (Sign-in screen), [`frontend/src/App.jsx`](https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/frontend/src/App.jsx) (Role routing), [`frontend/src/pages/AdminHome.jsx`](https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/frontend/src/pages/AdminHome.jsx) (Admin console), [`backend/src/main/java/com/example/demo/hostel/service/AdminService.java`](https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/service/AdminService.java) (Admin operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Portal frontend"]
  node_app["Role routing<br/>[App.jsx]"]
  node_login["Sign-in screen<br/>[Login.jsx]"]
  node_studentui["Student portal<br/>[StudentHome.jsx]"]
  node_adminui["Admin console<br/>[AdminHome.jsx]"]
  node_location["Room validation<br/>[hostelLocation.js]"]
  node_comingsoon["Coming-soon view<br/>[ComingSoon.jsx]"]
end

subgraph group_backend["Backend services"]
  node_authcontroller["Authentication API"]
  node_authservice["Account authentication<br/>[AuthService.java]"]
  node_security["Access security"]
  node_complaintcontroller["Complaint API"]
  node_studentservice["Student operations"]
  node_complaintservice["Complaint handling"]
  node_transitions["Status transitions"]
  node_admincontroller["Admin API"]
  node_adminservice["Admin operations<br/>[AdminService.java]"]
  node_filter["Complaint filtering"]
end

subgraph group_data["Complaint data"]
  node_complaintrepo[("Complaint records")]
  node_userrepo[("User records")]
end

node_student(("Student"))
node_admin(("Administrator"))
node_google(("Google sign-in"))
node_supabase[("Supabase database")]

node_student -->|"signs in"| node_login
node_admin -->|"signs in"| node_login
node_google -->|"provides credential"| node_login
node_login -->|"verifies token"| node_authcontroller
node_app -->|"checks role"| node_authcontroller
node_app -->|"routes to"| node_login
node_app -->|"routes student"| node_studentui
node_app -->|"routes admin"| node_adminui
node_studentui -->|"validates rooms"| node_location
node_adminui -->|"validates rooms"| node_location
node_adminui -->|"shows view"| node_comingsoon
node_studentui -.->|"uses complaint API"| node_complaintcontroller
node_adminui -.->|"uses admin API"| node_admincontroller
node_complaintcontroller -.->|"delegates"| node_studentservice
node_studentservice -.->|"handles complaints"| node_complaintservice
node_admincontroller -.->|"delegates"| node_adminservice
node_adminservice -.->|"updates status"| node_transitions
node_complaintservice -.->|"accesses records"| node_complaintrepo
node_adminservice -.->|"accesses records"| node_complaintrepo
node_adminservice -.->|"filters complaints"| node_filter
node_authcontroller -.->|"delegates"| node_authservice
node_authservice -.->|"accesses accounts"| node_userrepo
node_security -.->|"secures endpoints"| node_authcontroller
node_complaintrepo -.->|"stores data"| node_supabase
node_userrepo -.->|"stores data"| node_supabase

click node_app "https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/frontend/src/App.jsx"
click node_login "https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/frontend/src/pages/Login.jsx"
click node_studentui "https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/frontend/src/pages/StudentHome.jsx"
click node_adminui "https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/frontend/src/pages/AdminHome.jsx"
click node_location "https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/frontend/src/utils/hostelLocation.js"
click node_comingsoon "https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/frontend/src/pages/ComingSoon.jsx"
click node_authcontroller "https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/controller/AuthController.java"
click node_authservice "https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/service/AuthService.java"
click node_security "https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/config/SecurityConfig.java"
click node_complaintcontroller "https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/controller/ComplaintController.java"
click node_studentservice "https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/service/StudentService.java"
click node_complaintservice "https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/service/ComplaintService.java"
click node_transitions "https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/service/ComplaintTransitionService.java"
click node_admincontroller "https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/controller/AdminController.java"
click node_adminservice "https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/service/AdminService.java"
click node_filter "https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/specification/ComplaintSpecification.java"
click node_complaintrepo "https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/repository/ComplaintRepository.java"
click node_userrepo "https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/repository/UserRepository.java"

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_studentui,node_adminui,node_location,node_comingsoon toneBlue
class node_authcontroller,node_authservice,node_security,node_complaintcontroller,node_studentservice,node_complaintservice,node_transitions,node_admincontroller,node_adminservice,node_filter,node_supabase toneAmber
class node_complaintrepo,node_userrepo toneMint
class node_student,node_admin,node_google toneIndigo
```

## Components

### Portal frontend

- [Role routing](https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Sign-in screen](https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/frontend/src/pages/Login.jsx): `frontend/src/pages/Login.jsx`
- [Student portal](https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/frontend/src/pages/StudentHome.jsx): `frontend/src/pages/StudentHome.jsx`
- [Admin console](https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/frontend/src/pages/AdminHome.jsx): `frontend/src/pages/AdminHome.jsx`
- [Room validation](https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/frontend/src/utils/hostelLocation.js): `frontend/src/utils/hostelLocation.js`
- [Coming-soon view](https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/frontend/src/pages/ComingSoon.jsx): `frontend/src/pages/ComingSoon.jsx`

### Backend services

- [Authentication API](https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/controller/AuthController.java): `backend/src/main/java/com/example/demo/hostel/controller/AuthController.java`
- [Account authentication](https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/service/AuthService.java): `backend/src/main/java/com/example/demo/hostel/service/AuthService.java`
- [Access security](https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/config/SecurityConfig.java): `backend/src/main/java/com/example/demo/hostel/config/SecurityConfig.java`
- [Complaint API](https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/controller/ComplaintController.java): `backend/src/main/java/com/example/demo/hostel/controller/ComplaintController.java`
- [Student operations](https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/service/StudentService.java): `backend/src/main/java/com/example/demo/hostel/service/StudentService.java`
- [Complaint handling](https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/service/ComplaintService.java): `backend/src/main/java/com/example/demo/hostel/service/ComplaintService.java`
- [Status transitions](https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/service/ComplaintTransitionService.java): `backend/src/main/java/com/example/demo/hostel/service/ComplaintTransitionService.java`
- [Admin API](https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/controller/AdminController.java): `backend/src/main/java/com/example/demo/hostel/controller/AdminController.java`
- [Admin operations](https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/service/AdminService.java): `backend/src/main/java/com/example/demo/hostel/service/AdminService.java`
- [Complaint filtering](https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/specification/ComplaintSpecification.java): `backend/src/main/java/com/example/demo/hostel/specification/ComplaintSpecification.java`

### Complaint data

- [Complaint records](https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/repository/ComplaintRepository.java): `backend/src/main/java/com/example/demo/hostel/repository/ComplaintRepository.java`
- [User records](https://github.com/fireproof-zarry/hostel-complaints-ticketing-system/blob/main/backend/src/main/java/com/example/demo/hostel/repository/UserRepository.java): `backend/src/main/java/com/example/demo/hostel/repository/UserRepository.java`

### Other components

- **Student**
- **Administrator**
- **Google sign-in**
- **Supabase database**

## Connections

- Student → Sign-in screen: signs in (evidence: `frontend/src/pages/Login.jsx`)
- Administrator → Sign-in screen: signs in (evidence: `frontend/src/pages/Login.jsx`)
- Google sign-in → Sign-in screen: provides credential (evidence: `frontend/src/pages/Login.jsx`)
- Sign-in screen → Authentication API: verifies token (evidence: `frontend/src/pages/Login.jsx`)
- Role routing → Authentication API: checks role (evidence: `frontend/src/App.jsx`)
- Role routing → Sign-in screen: routes to (evidence: `frontend/src/App.jsx`)
- Role routing → Student portal: routes student (evidence: `frontend/src/App.jsx`)
- Role routing → Admin console: routes admin (evidence: `frontend/src/App.jsx`)
- Student portal → Room validation: validates rooms (evidence: `frontend/src/pages/StudentHome.jsx`)
- Admin console → Room validation: validates rooms (evidence: `frontend/src/pages/AdminHome.jsx`)
- Admin console → Coming-soon view: shows view (evidence: `frontend/src/pages/AdminHome.jsx`)
- Student portal → Complaint API: uses complaint API
- Admin console → Admin API: uses admin API
- Complaint API → Student operations: delegates
- Student operations → Complaint handling: handles complaints
- Admin API → Admin operations: delegates
- Admin operations → Status transitions: updates status
- Complaint handling → Complaint records: accesses records
- Admin operations → Complaint records: accesses records
- Admin operations → Complaint filtering: filters complaints
- Authentication API → Account authentication: delegates
- Account authentication → User records: accesses accounts
- Access security → Authentication API: secures endpoints
- Complaint records → Supabase database: stores data
- User records → Supabase database: stores data
