ranjith1089/saloon_management

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.