# ranjith1089/saloon_management architecture

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

- Interactive diagram: https://gitdiagram.com/ranjith1089/saloon_management
- Repository: https://github.com/ranjith1089/saloon_management

## Overview

#### Purpose and Deployment
A full-stack, multi-branch salon/spa operations SaaS: staff-facing operations, POS, customer portal, public booking widget, growth tooling, and administration. The React SPA is deployed to Vercel; the Express API and PostgreSQL run on Railway. Primary entry points are `frontend/src/main.tsx`, `frontend/src/App.tsx`, `backend/src/server.ts`, and `backend/src/app.ts`.

#### Frontend Route and UI Boundary
React/Vite provides distinct public, authenticated operational, and customer-portal experiences. `frontend/src/App.tsx` owns route composition; `frontend/src/layouts/DashboardLayout.tsx` frames protected back-office screens, while `frontend/src/pages/PublicBooking.tsx` implements the unauthenticated/embed-capable `/book/:branchId` flow. Guards in `frontend/src/components/ProtectedRoute.tsx` and `frontend/src/components/RoleGuard.tsx` enforce client-side navigation constraints.

#### API Composition and Request Pipeline
Express routers expose versioned resource APIs and dispatch to thin controllers, then services. `backend/src/routes/index.ts` is the API aggregation point; controllers in `backend/src/controllers/` translate requests, while domain logic resides in `backend/src/services/`. Authentication, validation, authorization/scoping, and consistent error handling form the request boundary through `backend/src/middlewares/auth.ts`, `backend/src/middlewares/validate.ts`, and `backend/src/middlewares/errorHandler.ts`. Public booking/inquiry routes remain intentionally unauthenticated but are rate-limited at the application level.

#### Identity, Roles, and Scope
JWT access/refresh authentication and bcrypt-backed credentials support ADMIN, MANAGER, STAFF, and CUSTOMER roles. `backend/src/services/auth.service.ts` owns auth behavior; `backend/src/services/access-control.service.ts` manages permission policy; `backend/src/utils/scope.ts` applies server-side ownership and staff/branch visibility restrictions. Frontend session state and token persistence are centralized in `frontend/src/store/authStore.ts` and HTTP interception in `frontend/src/services/api.ts`.

#### Booking-to-Revenue Operations
Booking is the central operational lifecycle, including scheduled and walk-in customers, staff assignment, status changes, payment collection, discounts, memberships, and referral effects. `backend/src/services/booking.service.ts` is the transactional authority, including concurrency protection for booking creation. The operational UI spans `frontend/src/pages/Bookings.tsx`, calendar/staff-grid components, and `frontend/src/pages/Sales.tsx`, where a unified ticket can combine products, services, and pending bookings. Finance, commission, and reporting consume finalized booking/sale data via `backend/src/services/finance.service.ts`, `backend/src/services/commission.service.ts`, and `backend/src/services/report.service.ts`.

#### Catalog, Branch, and Customer Domains
Multi-branch separation governs staff, schedules, service pricing, tax/payment configuration, inventory stock, and reporting. The persistence contract is centralized in `backend/prisma/schema.prisma`; branch, catalog, product-stock, membership, coupon, and customer business rules are separated across `backend/src/services/branch.service.ts`, `backend/src/services/product.service.ts`, and `backend/src/services/membership.service.ts`. Prisma migrations establish the evolving PostgreSQL schema under `backend/prisma/migrations/`.

#### External Integrations and Runtime Operations
Node.js 20/TypeScript runs the Express backend; React 18/Vite/Tailwind runs the browser application. Prisma connects to Railway PostgreSQL. Cloudinary handles branding/staff media via `backend/src/config/cloudinary.ts`; Meta WhatsApp Cloud API is integrated through `backend/src/config/whatsapp.ts` and `backend/src/services/whatsapp.service.ts`, primarily for notifications and test sends. Deployment initialization uses `backend/prisma/bootstrap.ts` before migrations/seeding, with Railway configuration in `backend/railway.json` and Vercel configuration in `vercel.json`.

Main entry points: [`frontend/src/App.tsx`](https://github.com/ranjith1089/saloon_management/blob/main/frontend/src/App.tsx) (Routes & app shell), [`backend/src/app.ts`](https://github.com/ranjith1089/saloon_management/blob/main/backend/src/app.ts) (API application), [`backend/prisma/schema.prisma`](https://github.com/ranjith1089/saloon_management/blob/main/backend/prisma/schema.prisma) (Prisma data model), [`backend/src/routes/index.ts`](https://github.com/ranjith1089/saloon_management/blob/main/backend/src/routes/index.ts) (Versioned API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React SPA"]
  node_spa_entry["SPA entry<br/>React/Vite bootstrap<br/>[main.tsx]"]
  node_route_shell["Routes &amp; app shell<br/>route composition<br/>[App.tsx]"]
  node_dashboard["Back-office dashboard<br/>protected layout"]
  node_public_booking_ui["Public booking widget<br/>public booking UI<br/>[PublicBooking.tsx]"]
  node_operations_ui["Booking &amp; sales UI<br/>operations screens<br/>[Bookings.tsx]"]
  node_client_auth["Client auth boundary<br/>session and API client<br/>[authStore.ts]"]
end

subgraph group_api["Express API"]
  node_server["API server<br/>Express bootstrap<br/>[server.ts]"]
  node_api_app["API application<br/>Express request boundary<br/>[app.ts]"]
  node_api_routes["Versioned API routes<br/>router aggregation<br/>[index.ts]"]
  node_request_boundary["Auth, validation &amp; errors<br/>middleware pipeline<br/>[auth.ts]"]
  node_identity_access["Identity &amp; access policy<br/>auth and authorization services<br/>[auth.service.ts]"]
  node_booking_ops["Booking lifecycle<br/>transactional domain service<br/>[booking.service.ts]"]
  node_sales_reporting["Revenue &amp; reporting<br/>finance domain services<br/>[finance.service.ts]"]
  node_branch_catalog["Branch &amp; catalog domains<br/>business services<br/>[branch.service.ts]"]
  node_notifications["WhatsApp notifications<br/>integration service"]
end

subgraph group_data["Data &amp; integrations"]
  node_prisma_schema["Prisma data model<br/>persistence contract<br/>[schema.prisma]"]
  node_postgres[("Railway PostgreSQL<br/>relational database")]
  node_cloudinary["Cloudinary<br/>media platform<br/>[cloudinary.ts]"]
  node_whatsapp["Meta WhatsApp Cloud API<br/>messaging platform<br/>[whatsapp.ts]"]
end

node_spa_entry -->|"mounts"| node_route_shell
node_route_shell -->|"protected operations"| node_dashboard
node_route_shell -->|"public /book/:branchId"| node_public_booking_ui
node_route_shell -->|"operational routes"| node_operations_ui
node_route_shell -->|"session guards"| node_client_auth
node_client_auth -->|"authenticated HTTP"| node_api_app
node_public_booking_ui -->|"public booking requests"| node_api_app
node_operations_ui -->|"booking and sales requests"| node_api_app
node_server -->|"starts"| node_api_app
node_api_app -->|"applies middleware"| node_request_boundary
node_request_boundary -->|"dispatches authorized requests"| node_api_routes
node_api_routes -->|"auth and policy actions"| node_identity_access
node_api_routes -->|"booking operations"| node_booking_ops
node_api_routes -->|"branch and catalog operations"| node_branch_catalog
node_booking_ops -->|"finalized revenue data"| node_sales_reporting
node_booking_ops -->|"booking notifications"| node_notifications
node_identity_access -->|"identity records"| node_prisma_schema
node_booking_ops -->|"transactional model"| node_prisma_schema
node_branch_catalog -->|"branch-scoped data"| node_prisma_schema
node_sales_reporting -->|"financial data"| node_prisma_schema
node_prisma_schema -->|"mapped to"| node_postgres
node_branch_catalog -->|"media assets"| node_cloudinary
node_notifications -->|"sends messages"| node_whatsapp

click node_spa_entry "https://github.com/ranjith1089/saloon_management/blob/main/frontend/src/main.tsx"
click node_route_shell "https://github.com/ranjith1089/saloon_management/blob/main/frontend/src/App.tsx"
click node_dashboard "https://github.com/ranjith1089/saloon_management/blob/main/frontend/src/layouts/DashboardLayout.tsx"
click node_public_booking_ui "https://github.com/ranjith1089/saloon_management/blob/main/frontend/src/pages/PublicBooking.tsx"
click node_operations_ui "https://github.com/ranjith1089/saloon_management/blob/main/frontend/src/pages/Bookings.tsx"
click node_client_auth "https://github.com/ranjith1089/saloon_management/blob/main/frontend/src/store/authStore.ts"
click node_server "https://github.com/ranjith1089/saloon_management/blob/main/backend/src/server.ts"
click node_api_app "https://github.com/ranjith1089/saloon_management/blob/main/backend/src/app.ts"
click node_api_routes "https://github.com/ranjith1089/saloon_management/blob/main/backend/src/routes/index.ts"
click node_request_boundary "https://github.com/ranjith1089/saloon_management/blob/main/backend/src/middlewares/auth.ts"
click node_identity_access "https://github.com/ranjith1089/saloon_management/blob/main/backend/src/services/auth.service.ts"
click node_booking_ops "https://github.com/ranjith1089/saloon_management/blob/main/backend/src/services/booking.service.ts"
click node_sales_reporting "https://github.com/ranjith1089/saloon_management/blob/main/backend/src/services/finance.service.ts"
click node_branch_catalog "https://github.com/ranjith1089/saloon_management/blob/main/backend/src/services/branch.service.ts"
click node_notifications "https://github.com/ranjith1089/saloon_management/blob/main/backend/src/services/whatsapp.service.ts"
click node_prisma_schema "https://github.com/ranjith1089/saloon_management/blob/main/backend/prisma/schema.prisma"
click node_cloudinary "https://github.com/ranjith1089/saloon_management/blob/main/backend/src/config/cloudinary.ts"
click node_whatsapp "https://github.com/ranjith1089/saloon_management/blob/main/backend/src/config/whatsapp.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_spa_entry,node_route_shell,node_dashboard,node_public_booking_ui,node_operations_ui,node_client_auth toneBlue
class node_server,node_api_app,node_api_routes,node_request_boundary,node_identity_access,node_booking_ops,node_sales_reporting,node_branch_catalog,node_notifications toneAmber
class node_prisma_schema,node_postgres,node_cloudinary,node_whatsapp toneMint
```

## Components

### React SPA

Vercel-hosted staff, customer, and public experiences.

- [SPA entry](https://github.com/ranjith1089/saloon_management/blob/main/frontend/src/main.tsx): React/Vite bootstrap · `frontend/src/main.tsx`
- [Routes & app shell](https://github.com/ranjith1089/saloon_management/blob/main/frontend/src/App.tsx): route composition · Separates public, operational, and customer portal routes. · `frontend/src/App.tsx`
- [Back-office dashboard](https://github.com/ranjith1089/saloon_management/blob/main/frontend/src/layouts/DashboardLayout.tsx): protected layout · `frontend/src/layouts/DashboardLayout.tsx`
- [Public booking widget](https://github.com/ranjith1089/saloon_management/blob/main/frontend/src/pages/PublicBooking.tsx): public booking UI · Embed-capable branch booking flow. · `frontend/src/pages/PublicBooking.tsx`
- [Booking & sales UI](https://github.com/ranjith1089/saloon_management/blob/main/frontend/src/pages/Bookings.tsx): operations screens · Manages bookings, calendar work, and unified sales tickets. · `frontend/src/pages/Bookings.tsx`
- [Client auth boundary](https://github.com/ranjith1089/saloon_management/blob/main/frontend/src/store/authStore.ts): session and API client · Persists tokens and applies HTTP interception. · `frontend/src/store/authStore.ts`

### Express API

Railway-hosted application and domain boundary.

- [API server](https://github.com/ranjith1089/saloon_management/blob/main/backend/src/server.ts): Express bootstrap · `backend/src/server.ts`
- [API application](https://github.com/ranjith1089/saloon_management/blob/main/backend/src/app.ts): Express request boundary · Applies rate limits and shared middleware. · `backend/src/app.ts`
- [Versioned API routes](https://github.com/ranjith1089/saloon_management/blob/main/backend/src/routes/index.ts): router aggregation · `backend/src/routes/index.ts`
- [Auth, validation & errors](https://github.com/ranjith1089/saloon_management/blob/main/backend/src/middlewares/auth.ts): middleware pipeline · Authenticates, validates, scopes, and normalizes failures. · `backend/src/middlewares/auth.ts`
- [Identity & access policy](https://github.com/ranjith1089/saloon_management/blob/main/backend/src/services/auth.service.ts): auth and authorization services · JWT credentials, roles, permissions, and branch/staff visibility. · `backend/src/services/auth.service.ts`
- [Booking lifecycle](https://github.com/ranjith1089/saloon_management/blob/main/backend/src/services/booking.service.ts): transactional domain service · Coordinates booking creation, assignment, status, and downstream effects. · `backend/src/services/booking.service.ts`
- [Revenue & reporting](https://github.com/ranjith1089/saloon_management/blob/main/backend/src/services/finance.service.ts): finance domain services · Consumes finalized booking and sale data for finance, commissions, and reports. · `backend/src/services/finance.service.ts`
- [Branch & catalog domains](https://github.com/ranjith1089/saloon_management/blob/main/backend/src/services/branch.service.ts): business services · Controls branches, pricing, stock, memberships, coupons, and customers. · `backend/src/services/branch.service.ts`
- [WhatsApp notifications](https://github.com/ranjith1089/saloon_management/blob/main/backend/src/services/whatsapp.service.ts): integration service · `backend/src/services/whatsapp.service.ts`

### Data & integrations

- [Prisma data model](https://github.com/ranjith1089/saloon_management/blob/main/backend/prisma/schema.prisma): persistence contract · Defines multi-branch operational data and relationships. · `backend/prisma/schema.prisma`
- **Railway PostgreSQL**: relational database
- [Cloudinary](https://github.com/ranjith1089/saloon_management/blob/main/backend/src/config/cloudinary.ts): media platform · Stores branding and staff media. · `backend/src/config/cloudinary.ts`
- [Meta WhatsApp Cloud API](https://github.com/ranjith1089/saloon_management/blob/main/backend/src/config/whatsapp.ts): messaging platform · `backend/src/config/whatsapp.ts`

## Connections

- SPA entry → Routes & app shell: mounts
- Routes & app shell → Back-office dashboard: protected operations
- Routes & app shell → Public booking widget: public /book/:branchId
- Routes & app shell → Booking & sales UI: operational routes
- Routes & app shell → Client auth boundary: session guards
- Client auth boundary → API application: authenticated HTTP
- Public booking widget → API application: public booking requests
- Booking & sales UI → API application: booking and sales requests
- API server → API application: starts
- API application → Auth, validation & errors: applies middleware
- Auth, validation & errors → Versioned API routes: dispatches authorized requests
- Versioned API routes → Identity & access policy: auth and policy actions
- Versioned API routes → Booking lifecycle: booking operations
- Versioned API routes → Branch & catalog domains: branch and catalog operations
- Booking lifecycle → Revenue & reporting: finalized revenue data
- Booking lifecycle → WhatsApp notifications: booking notifications
- Identity & access policy → Prisma data model: identity records
- Booking lifecycle → Prisma data model: transactional model
- Branch & catalog domains → Prisma data model: branch-scoped data
- Revenue & reporting → Prisma data model: financial data
- Prisma data model → Railway PostgreSQL: mapped to
- Branch & catalog domains → Cloudinary: media assets
- WhatsApp notifications → Meta WhatsApp Cloud API: sends messages