✂️ StyleSynk

AI-Powered Omnichannel Salon Management Platform

Book smarter. Serve faster. Grow together.

---

Overview

StyleSynk is a full-stack salon management system built for multi-branch operations. Customers describe appointments in plain language ("Need a facial tomorrow evening") and the AI auto-fills the booking form. Behind the scenes, every action — billing, commissions, inventory, loyalty points — executes as a single atomic transaction.

Hackathon MVP — production-style architecture with real DB transactions, FK relationships, Socket.IO, and shared services.

---

Quick Start

Prerequisites

• Node.js 18+
• PostgreSQL 14+
• A Groq API key (free tier works)

1. Clone & Install

git clone <repo-url>
cd StyleSynk

# Server dependencies
cd server && npm install

# Client dependencies
cd ../client && npm install

2. Configure Environment

cd server
cp .env.example .env
# Fill in DB_*, JWT_SECRET, and GROQ_API_KEY

3. Set Up the Database

# Create the database
psql -U postgres -c "CREATE DATABASE stylesynk;"

# Run schema — 16 tables, indexes, triggers
psql -U postgres -d stylesynk -f src/database/schema.sql

# Seed demo data — 3 branches, 10 staff, 15 customers, 50 appointments
psql -U postgres -d stylesynk -f src/database/seed.sql

4. Run

# Terminal 1 — API server
cd server && npm run dev
# → http://localhost:5000

# Terminal 2 — React frontend
cd client && npm run dev
# → http://localhost:5173

---

Docker

The fastest way to get everything running:

cp server/.env.example server/.env
# Set GROQ_API_KEY in server/.env

docker-compose up -d

Service	URL
API	http://localhost:5000
Frontend	http://localhost:5173
Database	Auto-seeded on first run

---

Demo Credentials

The login page has one-click fill buttons for all accounts.

Role	Email	Password
Owner	owner@stylesynk.com	Password123!
Branch Manager	manager.banjara@stylesynk.com	Password123!
Receptionist	recep.banjara@stylesynk.com	Password123!
Stylist	stylist1@stylesynk.com	Password123!

---

How It All Connects

Customer says: "Need a facial tomorrow evening"
        │
        ▼
POST /api/ai/parse-booking         ← Groq llama-3.1-8b-instant
        │  Parsed JSON auto-fills BookingModal
        ▼
User confirms → POST /api/appointments
        │  pg_advisory_xact_lock(staff_id)  ← concurrency-safe
        │  Collision check inside transaction
        │  INSERT appointment → COMMIT
        ▼
Socket.IO: appointment:created     → all branch clients update in real-time
        │
        ▼
Service completed → POST /api/billing/create   (single atomic transaction)
        │  1. Create bill record
        │  2. Insert invoice items
        │  3. Calculate GST (18%)
        │  4. Apply membership discount
        │  5. Calculate stylist commissions
        │  6. Deduct product inventory
        │  7. Award loyalty points (₹10 = 1 point)
        │  8. Insert notification
        │  9. Emit bill:closed + inventory:low via Socket.IO
        ▼
Analytics reads live from bills table — no extra calls needed

---

API Reference

Endpoint	Method	Auth	Description
/api/auth/login	POST	—	JWT login
/api/auth/register	POST	—	Register user
/api/auth/me	GET	✓	Current user
/api/appointments	GET	✓	Branch-scoped list
/api/appointments	POST	✓	Advisory-lock safe booking
/api/appointments/availability	GET	✓	Available slots
/api/customer/book	POST	✓	Customer self-service booking
/api/customer/loyalty	GET	✓	Loyalty balance + history
/api/billing/create	POST	✓	POS bill + 5 cascade triggers
/api/ai/parse-booking	POST	✓	Natural language → booking JSON
/api/analytics/overview	GET	✓	KPI dashboard
/api/inventory	GET	✓	Stock levels by branch
/api/commissions	GET	✓	Stylist earnings report
/api/notifications/:user_id	GET	✓	User notifications

---

Architecture

server/src/
├── config/         db.js (Pool), groq.js
├── controllers/    Thin — delegate to services
├── services/       collision.js   ← advisory lock
│                   invoice.js     ← billing orchestration
│                   commission.js  ← per-stylist earnings
│                   inventory.js   ← stock deduction
│                   loyalty.js     ← points engine
│                   notification.js ← insert + Socket.IO emit
├── routes/         RBAC-guarded per endpoint
├── middleware/     verifyToken, requireMinRole
├── socket/         Branch rooms, user rooms, staff rooms
├── ai/             parser.js (Groq + fallback)
└── utils/          response.js, dateUtils.js

---

Role Permissions

Action	Owner	Manager	Receptionist	Stylist	Customer
All branches	✅	❌	❌	❌	❌
Own branch data	✅	✅	✅	✅	❌
Create appointments	✅	✅	✅	❌	✅ †
POS / Billing	✅	✅	✅	❌	❌
View commissions	✅	✅	❌	✅ †	❌
Analytics	✅	✅	✅	❌	❌

† Scoped to own records only

---

Tech Stack

Layer	Technology
Frontend	React 18, React Router v6, Recharts
Styling	Vanilla CSS (custom design system)
Backend	Node.js, Express
Database	PostgreSQL 16 — pg driver, connection pool
Auth	JWT + RBAC middleware
Realtime	Socket.IO
AI	Groq API — llama-3.1-8b-instant
DevOps	Docker + docker-compose

---

_{Built with ☕ for the hackathon. Happy styling.}