# hhyalcin/my-hair architecture

> Architecture diagram of the GitHub repository hhyalcin/my-hair, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hhyalcin/my-hair
- Repository: https://github.com/hhyalcin/my-hair

## Overview

My Hair is a Flutter barber-discovery and appointment-booking app with a Node/Express API. The customer workflow is mobile app → shop discovery and staff/service availability → appointment booking and lifecycle updates; shop owners and staff also manage shops, services, schedules, and appointments, while customers can review completed visits and join a waitlist. The graph covers the documented mobile capabilities and sampled backend routes/controllers. Flutter application internals are not present in the supplied tree, so mobile is represented as a single client node; unsampled backend subsystems use only paths established by the tree or README.

Main entry points: [`backend/src/db`](https://github.com/hhyalcin/my-hair/tree/main/backend/src/db) (MySQL and cache), [`backend/src/index.js`](https://github.com/hhyalcin/my-hair/blob/main/backend/src/index.js) (Express API), [`backend/src/services/notification.service.js`](https://github.com/hhyalcin/my-hair/blob/main/backend/src/services/notification.service.js) (Notifications), [`backend/src/controllers/appointments.controller.js`](https://github.com/hhyalcin/my-hair/blob/main/backend/src/controllers/appointments.controller.js) (Appointment lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Mobile client"]
  node_mobile["Flutter app"]
end

subgraph group_api["API and identity"]
  node_api_runtime["Express API<br/>[index.js]"]
  node_auth_routes["Auth routes<br/>[auth.routes.js]"]
  node_auth_controller["Authentication<br/>[auth.controller.js]"]
  node_profile["Profile management"]
  node_database[("MySQL and cache")]
  node_firebase["Firebase services<br/>[firebase.js]"]
end

subgraph group_booking["Booking operations"]
  node_shops_routes["Shop routes<br/>[shops.routes.js]"]
  node_shops_controller["Shop discovery"]
  node_barber_routes["Barber routes<br/>[barber.routes.js]"]
  node_barber_controller["Shop operations"]
  node_appointments_routes["Appointment routes"]
  node_appointments_controller["Appointment lifecycle"]
  node_availability["Slot availability"]
end

subgraph group_engagement["Customer engagement"]
  node_waitlist_routes["Waitlist routes<br/>[waitlist.routes.js]"]
  node_waitlist_controller["Waitlist handling"]
  node_reviews_routes["Review routes<br/>[reviews.routes.js]"]
  node_reviews_controller["Review handling"]
  node_qr["Shop QR links<br/>[qr.controller.js]"]
  node_cron["Booking reminders"]
  node_notify["Notifications"]
  node_email["Email delivery<br/>[email.service.js]"]
end

node_customer(("Customer"))
node_shopstaff(("Shop owner or staff"))

node_customer -->|"uses"| node_mobile
node_shopstaff -->|"uses"| node_mobile
node_mobile -->|"API requests"| node_api_runtime
node_api_runtime -->|"dispatches"| node_auth_routes
node_api_runtime -->|"dispatches"| node_shops_routes
node_api_runtime -->|"dispatches"| node_barber_routes
node_api_runtime -->|"dispatches"| node_appointments_routes
node_api_runtime -->|"dispatches"| node_waitlist_routes
node_api_runtime -->|"dispatches"| node_reviews_routes
node_api_runtime -->|"dispatches"| node_qr
node_api_runtime -->|"dispatches"| node_profile
node_auth_routes -->|"calls"| node_auth_controller
node_auth_controller -->|"reads and writes"| node_database
node_auth_controller -->|"verifies identity"| node_firebase
node_auth_controller -->|"sends account email"| node_email
node_profile -->|"reads and writes"| node_database
node_shops_routes -->|"calls"| node_shops_controller
node_shops_controller -->|"queries shops"| node_database
node_barber_routes -->|"calls"| node_barber_controller
node_barber_controller -->|"manages shop data"| node_database
node_appointments_routes -->|"calls"| node_appointments_controller
node_appointments_controller -->|"selects available staff"| node_availability
node_appointments_controller -->|"books and updates"| node_database
node_appointments_controller -->|"triggers notices"| node_notify
node_appointments_controller -->|"invalidates cache"| node_availability
node_waitlist_routes -->|"calls"| node_waitlist_controller
node_waitlist_controller -->|"reads and writes"| node_database
node_waitlist_controller -->|"triggers notices"| node_notify
node_reviews_routes -->|"calls"| node_reviews_controller
node_reviews_controller -->|"stores reviews"| node_database
node_reviews_controller -->|"notifies owner"| node_notify
node_cron -->|"checks expiries"| node_database
node_cron -->|"triggers reminders"| node_notify
node_notify -->|"loads recipient data"| node_database
node_notify -->|"sends push notifications"| node_firebase
node_notify -->|"sends email notices"| node_email
node_email -->|"loads recipient email"| node_database
node_email -.-> node_firebase
node_qr -->|"resolves shop"| node_database

click node_mobile "https://github.com/hhyalcin/my-hair/tree/main/mobile"
click node_api_runtime "https://github.com/hhyalcin/my-hair/blob/main/backend/src/index.js"
click node_auth_routes "https://github.com/hhyalcin/my-hair/blob/main/backend/src/routes/auth.routes.js"
click node_auth_controller "https://github.com/hhyalcin/my-hair/blob/main/backend/src/controllers/auth.controller.js"
click node_profile "https://github.com/hhyalcin/my-hair/blob/main/backend/src/controllers/profile.controller.js"
click node_shops_routes "https://github.com/hhyalcin/my-hair/blob/main/backend/src/routes/shops.routes.js"
click node_shops_controller "https://github.com/hhyalcin/my-hair/blob/main/backend/src/controllers/shops.controller.js"
click node_barber_routes "https://github.com/hhyalcin/my-hair/blob/main/backend/src/routes/barber.routes.js"
click node_barber_controller "https://github.com/hhyalcin/my-hair/blob/main/backend/src/controllers/barber.controller.js"
click node_appointments_routes "https://github.com/hhyalcin/my-hair/blob/main/backend/src/routes/appointments.routes.js"
click node_appointments_controller "https://github.com/hhyalcin/my-hair/blob/main/backend/src/controllers/appointments.controller.js"
click node_availability "https://github.com/hhyalcin/my-hair/blob/main/backend/src/services/availability.service.js"
click node_waitlist_routes "https://github.com/hhyalcin/my-hair/blob/main/backend/src/routes/waitlist.routes.js"
click node_waitlist_controller "https://github.com/hhyalcin/my-hair/blob/main/backend/src/controllers/waitlist.controller.js"
click node_reviews_routes "https://github.com/hhyalcin/my-hair/blob/main/backend/src/routes/reviews.routes.js"
click node_reviews_controller "https://github.com/hhyalcin/my-hair/blob/main/backend/src/controllers/reviews.controller.js"
click node_qr "https://github.com/hhyalcin/my-hair/blob/main/backend/src/controllers/qr.controller.js"
click node_cron "https://github.com/hhyalcin/my-hair/tree/main/backend/src/crons"
click node_notify "https://github.com/hhyalcin/my-hair/blob/main/backend/src/services/notification.service.js"
click node_email "https://github.com/hhyalcin/my-hair/blob/main/backend/src/services/email.service.js"
click node_database "https://github.com/hhyalcin/my-hair/tree/main/backend/src/db"
click node_firebase "https://github.com/hhyalcin/my-hair/blob/main/backend/src/firebase.js"

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_mobile toneBlue
class node_api_runtime,node_auth_routes,node_auth_controller,node_profile,node_database,node_firebase toneAmber
class node_shops_routes,node_shops_controller,node_barber_routes,node_barber_controller,node_appointments_routes,node_appointments_controller,node_availability toneMint
class node_waitlist_routes,node_waitlist_controller,node_reviews_routes,node_reviews_controller,node_qr,node_cron,node_notify,node_email toneRose
class node_customer,node_shopstaff toneIndigo
```

## Components

### Mobile client

- [Flutter app](https://github.com/hhyalcin/my-hair/tree/main/mobile): `mobile`

### API and identity

- [Express API](https://github.com/hhyalcin/my-hair/blob/main/backend/src/index.js): `backend/src/index.js`
- [Auth routes](https://github.com/hhyalcin/my-hair/blob/main/backend/src/routes/auth.routes.js): `backend/src/routes/auth.routes.js`
- [Authentication](https://github.com/hhyalcin/my-hair/blob/main/backend/src/controllers/auth.controller.js): `backend/src/controllers/auth.controller.js`
- [Profile management](https://github.com/hhyalcin/my-hair/blob/main/backend/src/controllers/profile.controller.js): `backend/src/controllers/profile.controller.js`
- [MySQL and cache](https://github.com/hhyalcin/my-hair/tree/main/backend/src/db): `backend/src/db`
- [Firebase services](https://github.com/hhyalcin/my-hair/blob/main/backend/src/firebase.js): `backend/src/firebase.js`

### Booking operations

- [Shop routes](https://github.com/hhyalcin/my-hair/blob/main/backend/src/routes/shops.routes.js): `backend/src/routes/shops.routes.js`
- [Shop discovery](https://github.com/hhyalcin/my-hair/blob/main/backend/src/controllers/shops.controller.js): `backend/src/controllers/shops.controller.js`
- [Barber routes](https://github.com/hhyalcin/my-hair/blob/main/backend/src/routes/barber.routes.js): `backend/src/routes/barber.routes.js`
- [Shop operations](https://github.com/hhyalcin/my-hair/blob/main/backend/src/controllers/barber.controller.js): `backend/src/controllers/barber.controller.js`
- [Appointment routes](https://github.com/hhyalcin/my-hair/blob/main/backend/src/routes/appointments.routes.js): `backend/src/routes/appointments.routes.js`
- [Appointment lifecycle](https://github.com/hhyalcin/my-hair/blob/main/backend/src/controllers/appointments.controller.js): `backend/src/controllers/appointments.controller.js`
- [Slot availability](https://github.com/hhyalcin/my-hair/blob/main/backend/src/services/availability.service.js): `backend/src/services/availability.service.js`

### Customer engagement

- [Waitlist routes](https://github.com/hhyalcin/my-hair/blob/main/backend/src/routes/waitlist.routes.js): `backend/src/routes/waitlist.routes.js`
- [Waitlist handling](https://github.com/hhyalcin/my-hair/blob/main/backend/src/controllers/waitlist.controller.js): `backend/src/controllers/waitlist.controller.js`
- [Review routes](https://github.com/hhyalcin/my-hair/blob/main/backend/src/routes/reviews.routes.js): `backend/src/routes/reviews.routes.js`
- [Review handling](https://github.com/hhyalcin/my-hair/blob/main/backend/src/controllers/reviews.controller.js): `backend/src/controllers/reviews.controller.js`
- [Shop QR links](https://github.com/hhyalcin/my-hair/blob/main/backend/src/controllers/qr.controller.js): `backend/src/controllers/qr.controller.js`
- [Booking reminders](https://github.com/hhyalcin/my-hair/tree/main/backend/src/crons): `backend/src/crons`
- [Notifications](https://github.com/hhyalcin/my-hair/blob/main/backend/src/services/notification.service.js): `backend/src/services/notification.service.js`
- [Email delivery](https://github.com/hhyalcin/my-hair/blob/main/backend/src/services/email.service.js): `backend/src/services/email.service.js`

### Other components

- **Customer**
- **Shop owner or staff**

## Connections

- Customer → Flutter app: uses
- Shop owner or staff → Flutter app: uses
- Flutter app → Express API: API requests
- Express API → Auth routes: dispatches
- Express API → Shop routes: dispatches
- Express API → Barber routes: dispatches
- Express API → Appointment routes: dispatches
- Express API → Waitlist routes: dispatches
- Express API → Review routes: dispatches
- Express API → Shop QR links: dispatches
- Express API → Profile management: dispatches
- Auth routes → Authentication: calls
- Authentication → MySQL and cache: reads and writes
- Authentication → Firebase services: verifies identity
- Authentication → Email delivery: sends account email
- Profile management → MySQL and cache: reads and writes
- Shop routes → Shop discovery: calls
- Shop discovery → MySQL and cache: queries shops
- Barber routes → Shop operations: calls
- Shop operations → MySQL and cache: manages shop data
- Appointment routes → Appointment lifecycle: calls
- Appointment lifecycle → Slot availability: selects available staff
- Appointment lifecycle → MySQL and cache: books and updates
- Appointment lifecycle → Notifications: triggers notices
- Appointment lifecycle → Slot availability: invalidates cache
- Waitlist routes → Waitlist handling: calls
- Waitlist handling → MySQL and cache: reads and writes
- Waitlist handling → Notifications: triggers notices
- Review routes → Review handling: calls
- Review handling → MySQL and cache: stores reviews
- Review handling → Notifications: notifies owner
- Booking reminders → MySQL and cache: checks expiries
- Booking reminders → Notifications: triggers reminders
- Notifications → MySQL and cache: loads recipient data
- Notifications → Firebase services: sends push notifications
- Notifications → Email delivery: sends email notices
- Email delivery → MySQL and cache: loads recipient email
- Email delivery → Firebase services
- Shop QR links → MySQL and cache: resolves shop