# phutti19/ruts-realaids architecture

> Architecture diagram of the GitHub repository phutti19/ruts-realaids, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/phutti19/ruts-realaids
- Repository: https://github.com/phutti19/ruts-realaids

## Overview

RUTS-REALAIDS is a campus emergency-alert and first-aid management system with student and staff Next.js interfaces backed by a NestJS API and PostgreSQL. The principal flow is a student submitting a GPS-located incident, staff tracking and updating it, and the reporter receiving status updates; related care workflows cover visits, medication dispensing, and certificates. Other documented capabilities include appointments, inventory, reports, authentication, notifications, and PWA support. Several backend service and frontend feature paths are represented from the tree and README; their internal wiring is not asserted where source excerpts do not show it.

Main entry points: [`backend/src/main.ts`](https://github.com/phutti19/ruts-realaids/blob/main/backend/src/main.ts) (HTTP API), [`backend/src/database/db.service.ts`](https://github.com/phutti19/ruts-realaids/blob/main/backend/src/database/db.service.ts) (PostgreSQL), [`frontend/src/app/student`](https://github.com/phutti19/ruts-realaids/tree/main/frontend/src/app/student) (Student portal), [`frontend/src/app/staff`](https://github.com/phutti19/ruts-realaids/tree/main/frontend/src/app/staff) (Staff portal)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Web clients"]
  node_student["Student portal"]
  node_staff["Staff portal"]
end

subgraph group_api["API access"]
  node_api["HTTP API<br/>[main.ts]"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_access["Request authorization<br/>[auth.guard.ts]"]
end

subgraph group_care["Emergency and care"]
  node_emergency["Incident handling"]
  node_map["Incident maps<br/>[EmergencyMap.tsx]"]
  node_visits["Patient visits<br/>[visits.service.ts]"]
  node_certificates["Medical certificates"]
end

subgraph group_operations["Clinic operations"]
  node_appointments["Appointments"]
  node_medicines["Medicine inventory"]
  node_reports["Reports and statistics<br/>[reports.service.ts]"]
  node_settings["Administration settings"]
  node_users["User profiles<br/>[users.service.ts]"]
end

subgraph group_platform["Shared platform"]
  node_notifications["Notifications"]
  node_realtime["WebSocket updates<br/>[ws.service.ts]"]
  node_push["Push subscriptions"]
  node_pwa["Offline and install<br/>[sw.js]"]
  node_database[("PostgreSQL<br/>[db.service.ts]")]
  node_email["Email delivery<br/>[email.service.ts]"]
end

node_student_user(("Student"))
node_staff_user(("Clinic staff"))
node_browser_push["Web Push service"]

node_student_user -->|"uses"| node_student
node_staff_user -->|"uses"| node_staff
node_student -->|"requests"| node_api
node_staff -->|"requests"| node_api
node_api -.->|"authenticates"| node_auth
node_auth -->|"reads and writes"| node_database
node_api -->|"guards routes"| node_access
node_access -.->|"verifies JWT"| node_auth
node_api -->|"routes incidents"| node_emergency
node_emergency -.->|"stores incident data"| node_database
node_staff -->|"views incidents"| node_map
node_student -->|"reports emergencies"| node_api
node_api -->|"routes visits"| node_visits
node_visits -->|"requests certificate"| node_certificates
node_visits -.->|"persists care records"| node_database
node_api -->|"routes bookings"| node_appointments
node_appointments -->|"persists bookings"| node_database
node_api -->|"routes inventory"| node_medicines
node_medicines -.->|"persists stock"| node_database
node_api -.->|"routes reports"| node_reports
node_api -->|"routes administration"| node_settings
node_api -->|"routes profiles"| node_users
node_api -->|"routes notifications"| node_notifications
node_notifications -.->|"delivers live updates"| node_realtime
node_student -.->|"receives updates"| node_realtime
node_staff -.->|"receives updates"| node_realtime
node_push -.->|"subscribes"| node_browser_push
node_notifications -.->|"sends push"| node_browser_push
node_student -->|"runs offline"| node_pwa
node_auth -.->|"sends account email"| node_email
node_api -.->|"health and domain queries"| node_database

click node_student "https://github.com/phutti19/ruts-realaids/tree/main/frontend/src/app/student"
click node_staff "https://github.com/phutti19/ruts-realaids/tree/main/frontend/src/app/staff"
click node_api "https://github.com/phutti19/ruts-realaids/blob/main/backend/src/main.ts"
click node_auth "https://github.com/phutti19/ruts-realaids/blob/main/backend/src/modules/auth/auth.service.ts"
click node_access "https://github.com/phutti19/ruts-realaids/blob/main/backend/src/common/guards/auth.guard.ts"
click node_emergency "https://github.com/phutti19/ruts-realaids/blob/main/backend/src/modules/emergency/emergency.service.ts"
click node_map "https://github.com/phutti19/ruts-realaids/blob/main/frontend/src/components/maps/EmergencyMap.tsx"
click node_visits "https://github.com/phutti19/ruts-realaids/blob/main/backend/src/modules/visits/visits.service.ts"
click node_certificates "https://github.com/phutti19/ruts-realaids/blob/main/backend/src/modules/certificates/certificates.service.ts"
click node_appointments "https://github.com/phutti19/ruts-realaids/blob/main/backend/src/modules/appointments/appointments.service.ts"
click node_medicines "https://github.com/phutti19/ruts-realaids/blob/main/backend/src/modules/medicines/medicines.service.ts"
click node_reports "https://github.com/phutti19/ruts-realaids/blob/main/backend/src/modules/reports/reports.service.ts"
click node_settings "https://github.com/phutti19/ruts-realaids/blob/main/backend/src/modules/settings/settings.service.ts"
click node_users "https://github.com/phutti19/ruts-realaids/blob/main/backend/src/modules/users/users.service.ts"
click node_notifications "https://github.com/phutti19/ruts-realaids/blob/main/backend/src/modules/notifications/notifications.service.ts"
click node_realtime "https://github.com/phutti19/ruts-realaids/blob/main/backend/src/websocket/ws.service.ts"
click node_push "https://github.com/phutti19/ruts-realaids/blob/main/frontend/src/hooks/usePushNotification.ts"
click node_pwa "https://github.com/phutti19/ruts-realaids/blob/main/frontend/public/sw.js"
click node_database "https://github.com/phutti19/ruts-realaids/blob/main/backend/src/database/db.service.ts"
click node_email "https://github.com/phutti19/ruts-realaids/blob/main/backend/src/email/email.service.ts"

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_student,node_staff toneBlue
class node_api,node_auth,node_access toneAmber
class node_emergency,node_map,node_visits,node_certificates toneMint
class node_appointments,node_medicines,node_reports,node_settings,node_users toneRose
class node_notifications,node_realtime,node_push,node_pwa,node_database,node_email,node_student_user,node_staff_user,node_browser_push toneIndigo
```

## Components

### Web clients

- [Student portal](https://github.com/phutti19/ruts-realaids/tree/main/frontend/src/app/student): `frontend/src/app/student`
- [Staff portal](https://github.com/phutti19/ruts-realaids/tree/main/frontend/src/app/staff): `frontend/src/app/staff`

### API access

- [HTTP API](https://github.com/phutti19/ruts-realaids/blob/main/backend/src/main.ts): `backend/src/main.ts`
- [Authentication](https://github.com/phutti19/ruts-realaids/blob/main/backend/src/modules/auth/auth.service.ts): `backend/src/modules/auth/auth.service.ts`
- [Request authorization](https://github.com/phutti19/ruts-realaids/blob/main/backend/src/common/guards/auth.guard.ts): `backend/src/common/guards/auth.guard.ts`

### Emergency and care

- [Incident handling](https://github.com/phutti19/ruts-realaids/blob/main/backend/src/modules/emergency/emergency.service.ts): `backend/src/modules/emergency/emergency.service.ts`
- [Incident maps](https://github.com/phutti19/ruts-realaids/blob/main/frontend/src/components/maps/EmergencyMap.tsx): `frontend/src/components/maps/EmergencyMap.tsx`
- [Patient visits](https://github.com/phutti19/ruts-realaids/blob/main/backend/src/modules/visits/visits.service.ts): `backend/src/modules/visits/visits.service.ts`
- [Medical certificates](https://github.com/phutti19/ruts-realaids/blob/main/backend/src/modules/certificates/certificates.service.ts): `backend/src/modules/certificates/certificates.service.ts`

### Clinic operations

- [Appointments](https://github.com/phutti19/ruts-realaids/blob/main/backend/src/modules/appointments/appointments.service.ts): `backend/src/modules/appointments/appointments.service.ts`
- [Medicine inventory](https://github.com/phutti19/ruts-realaids/blob/main/backend/src/modules/medicines/medicines.service.ts): `backend/src/modules/medicines/medicines.service.ts`
- [Reports and statistics](https://github.com/phutti19/ruts-realaids/blob/main/backend/src/modules/reports/reports.service.ts): `backend/src/modules/reports/reports.service.ts`
- [Administration settings](https://github.com/phutti19/ruts-realaids/blob/main/backend/src/modules/settings/settings.service.ts): `backend/src/modules/settings/settings.service.ts`
- [User profiles](https://github.com/phutti19/ruts-realaids/blob/main/backend/src/modules/users/users.service.ts): `backend/src/modules/users/users.service.ts`

### Shared platform

- [Notifications](https://github.com/phutti19/ruts-realaids/blob/main/backend/src/modules/notifications/notifications.service.ts): `backend/src/modules/notifications/notifications.service.ts`
- [WebSocket updates](https://github.com/phutti19/ruts-realaids/blob/main/backend/src/websocket/ws.service.ts): `backend/src/websocket/ws.service.ts`
- [Push subscriptions](https://github.com/phutti19/ruts-realaids/blob/main/frontend/src/hooks/usePushNotification.ts): `frontend/src/hooks/usePushNotification.ts`
- [Offline and install](https://github.com/phutti19/ruts-realaids/blob/main/frontend/public/sw.js): `frontend/public/sw.js`
- [PostgreSQL](https://github.com/phutti19/ruts-realaids/blob/main/backend/src/database/db.service.ts): `backend/src/database/db.service.ts`
- [Email delivery](https://github.com/phutti19/ruts-realaids/blob/main/backend/src/email/email.service.ts): `backend/src/email/email.service.ts`

### Other components

- **Student**
- **Clinic staff**
- **Web Push service**

## Connections

- Student → Student portal: uses (evidence: `README.md`)
- Clinic staff → Staff portal: uses (evidence: `README.md`)
- Student portal → HTTP API: requests (evidence: `README.md`)
- Staff portal → HTTP API: requests (evidence: `README.md`)
- HTTP API → Authentication: authenticates
- Authentication → PostgreSQL: reads and writes (evidence: `backend/src/modules/auth/auth.service.ts`)
- HTTP API → Request authorization: guards routes (evidence: `backend/src/common/guards/auth.guard.ts`)
- Request authorization → Authentication: verifies JWT
- HTTP API → Incident handling: routes incidents
- Incident handling → PostgreSQL: stores incident data
- Staff portal → Incident maps: views incidents (evidence: `README.md`)
- Student portal → HTTP API: reports emergencies (evidence: `README.md`)
- HTTP API → Patient visits: routes visits
- Patient visits → Medical certificates: requests certificate (evidence: `backend/src/modules/visits/visits.controller.ts`)
- Patient visits → PostgreSQL: persists care records
- HTTP API → Appointments: routes bookings
- Appointments → PostgreSQL: persists bookings (evidence: `backend/src/modules/appointments/appointments.service.ts`)
- HTTP API → Medicine inventory: routes inventory
- Medicine inventory → PostgreSQL: persists stock
- HTTP API → Reports and statistics: routes reports
- HTTP API → Administration settings: routes administration
- HTTP API → User profiles: routes profiles
- HTTP API → Notifications: routes notifications
- Notifications → WebSocket updates: delivers live updates
- Student portal → WebSocket updates: receives updates
- Staff portal → WebSocket updates: receives updates
- Push subscriptions → Web Push service: subscribes
- Notifications → Web Push service: sends push
- Student portal → Offline and install: runs offline (evidence: `README.md`)
- Authentication → Email delivery: sends account email (evidence: `backend/src/modules/auth/auth.service.ts`)
- HTTP API → PostgreSQL: health and domain queries
