# yahya-mohamoud/hms architecture

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

- Interactive diagram: https://gitdiagram.com/yahya-mohamoud/hms
- Repository: https://github.com/yahya-mohamoud/hms

## Overview

Staywell Hotel Desk is a local-first staff operations system, not a public booking platform. Staff use the web app to authenticate, manage guests and reservations, check guests into stays, handle room status and folios through checkout, and review daily reports and audit activity. The API routes these workflows to PostgreSQL; private ID images use a separate optional S3-compatible store. The graph includes documented capabilities whose implementation was not sampled, but their internal call paths are not inferred.

Main entry points: [`apps/api/src/app.ts`](https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/app.ts) (HTTP API), [`apps/api/prisma/schema.prisma`](https://github.com/yahya-mohamoud/hms/blob/main/apps/api/prisma/schema.prisma) (PostgreSQL), [`apps/api/src/lib/audit.ts`](https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/lib/audit.ts) (Activity audit), [`apps/api/src/modules/guests/documents-router.ts`](https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/modules/guests/documents-router.ts) (ID documents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Staff interface"]
  node_webapp["Operations app<br/>[App.tsx]"]
  node_apiclient["API client<br/>[api.ts]"]
end

subgraph group_api["API and access"]
  node_apiapp["HTTP API<br/>[app.ts]"]
  node_auth["Authentication<br/>[router.ts]"]
  node_access["Role checks<br/>[auth.ts]"]
  node_users["Staff accounts<br/>[router.ts]"]
  node_audit["Activity audit<br/>[audit.ts]"]
end

subgraph group_frontdesk["Front desk operations"]
  node_guests["Guest profiles<br/>[router.ts]"]
  node_idimages["ID documents"]
  node_reservations["Reservations<br/>[router.ts]"]
  node_rooms["Room status<br/>[router.ts]"]
  node_stays["Stay lifecycle<br/>[router.ts]"]
end

subgraph group_finance["Finance and insights"]
  node_billing["Folios and payments<br/>[router.ts]"]
  node_reports["Reports and insights<br/>[router.ts]"]
end

subgraph group_persistence["Data and documents"]
  node_database[("PostgreSQL<br/>[schema.prisma]")]
  node_objectstore[("Private object store")]
end

node_staff(("Hotel staff"))

node_staff -->|"uses"| node_webapp
node_webapp -->|"uses"| node_apiclient
node_apiclient -->|"requests"| node_apiapp
node_apiapp -->|"routes"| node_auth
node_apiapp -->|"authenticates"| node_access
node_apiapp -->|"routes"| node_rooms
node_apiapp -->|"routes"| node_guests
node_apiapp -->|"routes"| node_idimages
node_apiapp -->|"routes"| node_reservations
node_apiapp -->|"routes"| node_stays
node_apiapp -->|"routes"| node_billing
node_apiapp -->|"routes"| node_reports
node_apiapp -->|"routes"| node_users
node_auth -->|"checks roles"| node_access
node_reservations -->|"reads and writes"| node_database
node_guests -->|"reads and writes"| node_database
node_idimages -->|"stores metadata"| node_database
node_idimages -->|"uploads images"| node_objectstore
node_objectstore -->|"signed downloads"| node_idimages
node_rooms -->|"reads and writes"| node_database
node_stays -->|"reads and writes"| node_database
node_billing -->|"reads and writes"| node_database
node_reports -->|"queries and saves"| node_database
node_users -->|"manages accounts"| node_database
node_auth -->|"checks accounts"| node_database
node_reservations -->|"logs actions"| node_audit
node_stays -->|"logs actions"| node_audit
node_billing -->|"logs actions"| node_audit
node_reports -->|"logs close"| node_audit
node_idimages -->|"logs uploads"| node_audit
node_audit -->|"writes activity"| node_database

click node_webapp "https://github.com/yahya-mohamoud/hms/blob/main/apps/web/src/App.tsx"
click node_apiclient "https://github.com/yahya-mohamoud/hms/blob/main/apps/web/src/lib/api.ts"
click node_apiapp "https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/app.ts"
click node_auth "https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/modules/auth/router.ts"
click node_access "https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/middleware/auth.ts"
click node_guests "https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/modules/guests/router.ts"
click node_idimages "https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/modules/guests/documents-router.ts"
click node_reservations "https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/modules/reservations/router.ts"
click node_rooms "https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/modules/rooms/router.ts"
click node_stays "https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/modules/stays/router.ts"
click node_billing "https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/modules/billing/router.ts"
click node_reports "https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/modules/reports/router.ts"
click node_users "https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/modules/users/router.ts"
click node_audit "https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/lib/audit.ts"
click node_database "https://github.com/yahya-mohamoud/hms/blob/main/apps/api/prisma/schema.prisma"

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_webapp,node_apiclient toneBlue
class node_apiapp,node_auth,node_access,node_users,node_audit toneAmber
class node_guests,node_idimages,node_reservations,node_rooms,node_stays toneMint
class node_billing,node_reports toneRose
class node_database,node_objectstore,node_staff toneIndigo
```

## Components

### Staff interface

- [Operations app](https://github.com/yahya-mohamoud/hms/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [API client](https://github.com/yahya-mohamoud/hms/blob/main/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`

### API and access

- [HTTP API](https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Authentication](https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/modules/auth/router.ts): `apps/api/src/modules/auth/router.ts`
- [Role checks](https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/middleware/auth.ts): `apps/api/src/middleware/auth.ts`
- [Staff accounts](https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/modules/users/router.ts): `apps/api/src/modules/users/router.ts`
- [Activity audit](https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/lib/audit.ts): `apps/api/src/lib/audit.ts`

### Front desk operations

- [Guest profiles](https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/modules/guests/router.ts): `apps/api/src/modules/guests/router.ts`
- [ID documents](https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/modules/guests/documents-router.ts): `apps/api/src/modules/guests/documents-router.ts`
- [Reservations](https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/modules/reservations/router.ts): `apps/api/src/modules/reservations/router.ts`
- [Room status](https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/modules/rooms/router.ts): `apps/api/src/modules/rooms/router.ts`
- [Stay lifecycle](https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/modules/stays/router.ts): `apps/api/src/modules/stays/router.ts`

### Finance and insights

- [Folios and payments](https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/modules/billing/router.ts): `apps/api/src/modules/billing/router.ts`
- [Reports and insights](https://github.com/yahya-mohamoud/hms/blob/main/apps/api/src/modules/reports/router.ts): `apps/api/src/modules/reports/router.ts`

### Data and documents

- [PostgreSQL](https://github.com/yahya-mohamoud/hms/blob/main/apps/api/prisma/schema.prisma): `apps/api/prisma/schema.prisma`
- **Private object store**

### Other components

- **Hotel staff**

## Connections

- Hotel staff → Operations app: uses (evidence: `README.md`)
- Operations app → API client: uses (evidence: `apps/web/src/App.tsx`)
- API client → HTTP API: requests (evidence: `README.md`)
- HTTP API → Authentication: routes (evidence: `apps/api/src/app.ts`)
- HTTP API → Role checks: authenticates (evidence: `apps/api/src/app.ts`)
- HTTP API → Room status: routes (evidence: `apps/api/src/app.ts`)
- HTTP API → Guest profiles: routes (evidence: `apps/api/src/app.ts`)
- HTTP API → ID documents: routes (evidence: `apps/api/src/app.ts`)
- HTTP API → Reservations: routes (evidence: `apps/api/src/app.ts`)
- HTTP API → Stay lifecycle: routes (evidence: `apps/api/src/app.ts`)
- HTTP API → Folios and payments: routes (evidence: `apps/api/src/app.ts`)
- HTTP API → Reports and insights: routes (evidence: `apps/api/src/app.ts`)
- HTTP API → Staff accounts: routes (evidence: `apps/api/src/app.ts`)
- Authentication → Role checks: checks roles (evidence: `apps/api/src/modules/auth/router.ts`)
- Reservations → PostgreSQL: reads and writes (evidence: `apps/api/src/modules/reservations/router.ts`)
- Guest profiles → PostgreSQL: reads and writes (evidence: `apps/api/src/modules/guests/router.ts`)
- ID documents → PostgreSQL: stores metadata (evidence: `apps/api/src/modules/guests/documents-router.ts`)
- ID documents → Private object store: uploads images (evidence: `apps/api/src/modules/guests/documents-router.ts`)
- Private object store → ID documents: signed downloads (evidence: `apps/api/src/modules/guests/documents-router.ts`)
- Room status → PostgreSQL: reads and writes (evidence: `apps/api/src/modules/rooms/router.ts`)
- Stay lifecycle → PostgreSQL: reads and writes (evidence: `apps/api/src/modules/stays/router.ts`)
- Folios and payments → PostgreSQL: reads and writes (evidence: `apps/api/src/modules/billing/router.ts`)
- Reports and insights → PostgreSQL: queries and saves (evidence: `apps/api/src/modules/reports/router.ts`)
- Staff accounts → PostgreSQL: manages accounts (evidence: `apps/api/src/modules/users/router.ts`)
- Authentication → PostgreSQL: checks accounts (evidence: `apps/api/src/modules/auth/router.ts`)
- Reservations → Activity audit: logs actions (evidence: `apps/api/src/modules/reservations/router.ts`)
- Stay lifecycle → Activity audit: logs actions (evidence: `apps/api/src/modules/stays/router.ts`)
- Folios and payments → Activity audit: logs actions (evidence: `apps/api/src/modules/billing/router.ts`)
- Reports and insights → Activity audit: logs close (evidence: `apps/api/src/modules/reports/router.ts`)
- ID documents → Activity audit: logs uploads (evidence: `apps/api/src/modules/guests/documents-router.ts`)
- Activity audit → PostgreSQL: writes activity (evidence: `apps/api/src/lib/audit.ts`)
