> ## Documentation Index > Fetch the complete documentation index at: https://docs.theroyalglow.in/llms.txt > Use this file to discover all available pages before exploring further. # High-Level Design > Architecture overview, technology decisions matrix, data model, auth design, and API patterns for Royal Glow. # High-Level Design ## Executive Summary Royal Glow Salon & Spa is a premium beauty and wellness establishment in Bengaluru, India. This document describes the high-level design of the full-stack digital operations platform. A **monolithic modular** monorepo on Next.js 16 + Neon + Cloudflare's edge, designed for 20k–50k users at **₹0/month**, India-first (DPDP, IST, paise, GST 18%), with Lighthouse ≥95 performance and 100 accessibility/SEO. ### Scale Targets | Name | Type | Description | | ------------------------- | -------------------- | ------------------------------------------------------- | | `Registered users` | `20,000–50,000` | Future-proof target | | `Daily active users` | `50–200` | Expected steady state | | `Concurrent users (peak)` | `50` | Load-test target | | `Application routes` | `~104 pages` | Customer (web) + admin (incl. staff self-service) + API | | `Database tables` | `38` | 15 Drizzle schema files | | `API endpoints` | `~90 route handlers` | Thin orchestrators across web + admin + jobs | | `Background jobs` | `19` | Scheduled + triggered + cron | ### Key Constraints | Name | Type | Description | | ------------------------- | ------------ | --------------------------------------------------------------- | | `Solo developer` | `constraint` | No microservices, minimal ops overhead, single consistent stack | | `₹0/month infrastructure` | `constraint` | All free tiers at launch | | `India-first` | `constraint` | DPDP Act, IST timezone, INR (paise), GST 18% | | `Premium brand` | `constraint` | Lighthouse ≥95 performance, 100 accessibility/SEO | ## Architecture Overview ### Layered Monorepo ```text theme={null} Presentation → API (thin) → Business Logic → Data Access → Database apps/{web,admin} apps/{web,admin}/api packages/business packages/db Neon PostgreSQL ``` | Name | Type | Description | | ------------------ | ----------------------------------------- | ----------------------------------------------------------------------------- | | `Presentation` | `apps/web + apps/admin (app, components)` | May import: business, db, types, errors. Must not import: nothing restricted. | | `API (thin)` | `apps/web/app/api + apps/admin/app/api` | May import: business, db, types, errors. Must not import: UI components. | | `Business Logic` | `packages/business` | May import: types, errors. Must not import: db, framework, UI. | | `Data Access` | `packages/db` | May import: types. Must not import: business, framework, UI. | | `Types/Validation` | `packages/types` | May import: nothing. Must not import: everything else. | ### Hosting Topology ```text theme={null} Browser/PWA │ HTTPS ▼ Cloudflare (DNS + DDoS + WAF) │ ├── Cloudflare Workers (web + admin via OpenNext adapter, edge SSR + API) └── Cloudflare KV (service catalog cache, 5-min TTL) │ ├── Render Singapore (Payload CMS) ├── Cloud Run (@rgss/invoicing PDF render service) ├── Neon PostgreSQL (4 branches: dev/test/pprd/prod) ├── Upstash Redis + QStash (cache + queue) ├── Cloudflare R2 (images, PDFs, backups) └── Ably (realtime WebSocket, 6 channels) ``` ## Technology Decisions Matrix | Category | Choice | Key Reason | | --------------------- | ----------------------------- | ----------------------------------------------- | | Framework | Next.js 16 (App Router) | SSR + SSG + API routes + edge-ready | | Runtime | Bun | 3x faster installs, native TypeScript | | Database | Neon PostgreSQL 16 | Branching, serverless, all jobs via QStash | | ORM | Drizzle ORM | Pure TypeScript, runs on CF Workers V8 | | Auth | Better Auth | Self-hosted, Google OAuth, RBAC plugin | | Edge Hosting | Cloudflare Workers (OpenNext) | Generous free tier, global edge | | Origin Hosting | Render (Singapore) | Free tier, closest to India | | Realtime | Ably | 6M messages/mo free vs Pusher's 200k/day | | CMS | Payload CMS v3 | Self-hosted Next.js plugin, zero vendor lock-in | | Email (transactional) | Resend | Modern DX, React Email templates | | Email (marketing) | Brevo | Unsubscribe management, DPDP-compliant | | Cache | Upstash Redis | Serverless, works on CF Workers | | File Storage | Cloudflare R2 | S3-compatible, zero egress fees | | Analytics | PostHog | 1M events/mo, feature flags, DPDP-compliant | | Error Monitoring | Sentry | Industry standard, CF Workers support | | Validation | Zod | TypeScript-native inference, industry standard | | Styling | Tailwind CSS v4 | Utility-first, design tokens | | Components | shadcn/ui + Radix | Copy-paste ownership, Radix accessibility | ## Data Architecture ### Database Strategy **Neon PostgreSQL 16** with Git-like branching. | Name | Type | Description | | ------ | ---------------- | ----------------------------------------- | | `prod` | `Production` | Never reset | | `pprd` | `Pre-production` | Auto-reset daily from prod + PII stripped | | `test` | `QA / CI` | Wiped and reseeded every CI run | | `dev` | `Development` | Developer sandbox | ### Data Model Overview (38 tables) | Domain | Tables | Key Entities | | --------------- | ------ | ---------------------------------------------------------------------------------------------------- | | Auth | 4 | `user`, `session`, `account`, `verification` | | Profiles | 2 | `customer_profile`, `staff_profile` | | Services | 3 | `service_category`, `service`, `service_staff` | | Scheduling | 4 | `staff_schedule`, `staff_time_off`, `holiday`, `waitlist` | | Bookings | 4 | `booking`, `booking_service`, `booking_note`, `booking_history` | | Billing | 2 | `invoice`, `invoice_item` | | SPA Memberships | 2 | `spa_membership`, `spa_membership_tier` | | Offers | 3 | `offer`, `offer_service`, `offer_redemption` | | CRM/Leads | 5 | `lead`, `lead_note`, `customer_tag`, `customer_tag_assignment`, `customer_note` | | Loyalty | 2 | `loyalty_account`, `loyalty_transaction` | | Notifications | 2 | `notification`, `push_subscription` | | Branches | 1 | `branch` | | System | 5 | `daily_sales_summary`, `monthly_gst_summary`, `audit_log`, `system_setting`, `feature_flag_override` | ### Key Data Conventions | Name | Type | Description | | ------------------ | -------------------- | ------------------------------------------------ | | `Primary keys` | `text via nanoid()` | Prevents enumeration attacks | | `Money` | `integer (paise)` | ₹1,000.00 = 100000 | | `Timestamps` | `timestamptz` | Stored UTC, displayed IST | | `Date display` | `DD/MM/YYYY` | en-IN locale | | `Currency display` | `₹1,00,000.00` | Indian numbering | | `Soft deletes` | `not used` | Hard deletes with audit\_log | | `Naming` | `snake_case` | Singular table names | | `Enums` | `native CREATE TYPE` | PostgreSQL enums | | `Snapshots` | `frozen` | Price/name on invoice\_item and booking\_service | | `GST` | `18% inclusive` | base = price ÷ 1.18 | ### Three-Layer Cache Hierarchy | Name | Type | Description | | --------------- | ----------------- | --------------------------------------------- | | `L1 (Edge)` | `Cloudflare KV` | TTL 5 min — service catalog, categories | | `L2 (Regional)` | `Upstash Redis` | TTL 5 min — slot availability per date/branch | | `L3 (Source)` | `Neon PostgreSQL` | Persistent — all business data | ## Authentication & Authorization ### Auth Architecture * **Provider:** Google OAuth 2.0 only (no email/password) * **Sessions:** PostgreSQL `session` table (HttpOnly, Secure, SameSite=Lax cookies) * **CSRF:** Built-in via Better Auth * **Token type:** Session-based (not JWT) — revocable, server-validated Six roles in ascending privilege: ```text theme={null} Customer → Staff → Receptionist → Manager → Owner → Developer ``` | Role | Access | | ------------ | ------------------------------------------------------------------------------- | | Customer | Public pages, own bookings/profile/gems | | Staff | Own schedule, assigned booking notes, leave requests | | Receptionist | Lowest admin role — bookings, billing, memberships, leave approvals | | Manager | Full operational access — staff, services, reports, settings | | Owner | Full business access including `admin.theroyalglow.in/users` | | Developer | Everything + `admin.theroyalglow.in/integrations`, `admin.theroyalglow.in/logs` | User clicks "Sign in with Google". Redirect to the Google consent screen (shows "Royal Glow Salon & Spa"). User grants consent and Google calls back with an auth code. Better Auth exchanges the code for tokens and creates/finds the user in the DB. A session is created and an HttpOnly cookie is set. Has a `customer_profile`? YES → homepage. NO → `/onboarding`. ## API Design ### Thin API Layer Pattern ```text theme={null} Request → Parse → Zod Validate → Business Logic → Response ``` API routes are thin orchestrators. No database queries in route handlers. ### Standard Response Shape ```typescript theme={null} // Success { success: true, data: T, meta?: { page, totalPages, totalCount } } // Error { success: false, error: { code, message, statusCode, requestId, retryable?, details? } } ``` ### API Groups | Name | Type | Description | | ----------------- | -------------------- | -------------------------------------------------- | | `Auth` | `catch-all per app` | Better Auth on web + admin (`/api/auth/[...all]`) | | `Customer` | `~20 endpoints` | theroyalglow\.in/api — authenticated + public | | `Admin` | `~50 endpoints` | admin.theroyalglow\.in/api — role-gated | | `Background Jobs` | `19 jobs` | admin.theroyalglow\.in/api/jobs — QStash signature | | `Webhooks` | `signature-verified` | Inbound integration webhooks | ## Non-Functional Requirements | Name | Type | Description | | -------------------------- | --------------- | ------------------------ | | `Latency` | `< 100ms` | Global response time | | `Availability` | `99.9%` | Uptime | | `Security` | `DPDP Act 2023` | India privacy compliance | | `Lighthouse Performance` | `≥ 95` | CI gate | | `Lighthouse Accessibility` | `100` | CI gate | | `Lighthouse SEO` | `100` | CI gate | | `Cost` | `₹0/month` | Infrastructure | | `Scalability` | `50 concurrent` | Peak users | | `RPO` | `~0 seconds` | Neon PITR | | `RTO` | `< 5 minutes` | Recovery time objective | | `Accessibility` | `WCAG 2.1 AA` | Compliance level | ## Related Pages State machines, sequences, indexes, and security implementation All 38 tables, enums, and ID formats Condensed architecture overview ## Related topics - [Low-Level Design](/content/docs/system-design/low-level-design.md) - [System Design](/content/docs/system-design/index.md) - [Tech Stack](/content/docs/tech-stack.md) - [Overview](/content/docs/index.md) - [Architecture](/content/docs/architecture.md)