> ## 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.

# Tech Stack

> Every technology used in the Royal Glow platform and why it was chosen.

# Tech Stack

Royal Glow is built for scale (20k–50k users), premium feel, and long-term maintainability by a single developer. Every technology choice is made with that constraint in mind.

<Info>
  **Total monthly infrastructure cost at launch: ₹0.** Every service runs on a free tier that is generous enough for a salon at this scale. The whole stack is edge-first, India-first (DPDP, IST, paise, GST 18%), and chosen so one developer can run it with minimal ops overhead.
</Info>

## The Stack by Layer

Browse each layer of the platform. Every choice below is in production use.

<Tabs>
  <Tab title="Core & UI">
    | Layer      | Technology                      | Why                                                                              |
    | ---------- | ------------------------------- | -------------------------------------------------------------------------------- |
    | Runtime    | **Bun**                         | Faster than Node.js for installs, test runs, and scripts                         |
    | Language   | **TypeScript** (strict)         | Type safety across the full stack — catches \~40% of bugs before tests run       |
    | Framework  | **Next.js 16.2.9** (App Router) | SSR, SSG, API routes, edge-ready. `params`/`searchParams` are Promises in v16.   |
    | UI         | **React**                       | Component model, ecosystem                                                       |
    | Styling    | **Tailwind CSS v4**             | Utility-first, design tokens, fast iteration                                     |
    | Components | **shadcn/ui**                   | Copy-paste Radix-based components — fully owned, zero runtime overhead           |
    | Animation  | **motion** (motion.dev)         | Page transitions, staggered reveals, micro-interactions — free tier              |
    | Monorepo   | **Turborepo + Bun workspaces**  | Bun manages packages; Turborepo handles task orchestration + incremental caching |

    <Info>
      **Why shadcn/ui:** components are copy-pasted into your repo — you own 100% of the code. Built on Radix UI primitives for production-tested accessibility, with zero runtime overhead.
    </Info>
  </Tab>

  <Tab title="Data & Auth">
    | Tool                   | Role                                                                                  |
    | ---------------------- | ------------------------------------------------------------------------------------- |
    | **Neon PostgreSQL 16** | Serverless Postgres with branching — 1 project, 4 environment branches, free tier     |
    | **Drizzle ORM**        | Pure TypeScript, no binary — edge-native, runs on Cloudflare Workers without adapters |
    | **Better Auth**        | Primary auth library — Google OAuth, RBAC plugin, session management                  |
    | **Better Auth Cloud**  | Free dashboard, audit logs, user management UI                                        |

    <Warning>
      **Why Drizzle over Prisma:** Prisma's Rust query engine binary cannot run in a V8 isolate (Cloudflare Workers) without workarounds or paid Prisma Accelerate. Drizzle is pure TypeScript and works everywhere.
    </Warning>

    Google OAuth only — no email/password. This eliminates credential stuffing, weak passwords, and reset flows. All salon customers in India have Google accounts.
  </Tab>

  <Tab title="Infrastructure">
    | Layer         | Technology                                                            |
    | ------------- | --------------------------------------------------------------------- |
    | Edge Hosting  | **Cloudflare Workers** (OpenNext adapter — `rgss-web`, `rgss-admin`)  |
    | CMS Hosting   | **Render** (Singapore, free tier — `rgss-cms`, `cms.theroyalglow.in`) |
    | Database      | **Neon DB** (PostgreSQL, 4 branches)                                  |
    | Realtime      | **Ably** (6M messages/mo free)                                        |
    | File Storage  | **Cloudflare R2** (10 GB free, zero egress)                           |
    | Cache + Queue | **Upstash Redis + QStash**                                            |
    | Edge Cache    | **Cloudflare KV** (service catalog, 5-min TTL)                        |
    | CMS           | **Payload CMS v3** (self-hosted on Render, media to R2)               |
    | Documentation | **Mintlify** — `docs.theroyalglow.in`                                 |
  </Tab>

  <Tab title="Email">
    | Tool            | Role                                                   |
    | --------------- | ------------------------------------------------------ |
    | **Resend**      | Transactional emails (invoices, booking confirmations) |
    | **React Email** | Email templates in React/TypeScript                    |
    | **Brevo**       | Marketing/bulk emails with unsubscribe management      |
  </Tab>

  <Tab title="Testing & Quality">
    | Tool                             | Purpose                                                         |
    | -------------------------------- | --------------------------------------------------------------- |
    | **Biome + Ultracite**            | Linting + formatting (replaces ESLint + Prettier — 100x faster) |
    | **Vitest**                       | Unit & integration testing                                      |
    | **React Testing Library**        | Component testing                                               |
    | **Playwright**                   | End-to-end testing (5 browsers)                                 |
    | **MSW**                          | API mocking (network-level, works in browser + Node)            |
    | **k6**                           | Load testing (target: 50 concurrent on pprd)                    |
    | **Lighthouse CI**                | Performance gate — ≥95 score required to merge                  |
    | **Trivy + Semgrep + Socket.dev** | Security scanning (deps, SAST, supply chain)                    |
    | **Husky + lint-staged**          | Pre-commit hooks (lint + format on staged files)                |
    | **Checkly**                      | Synthetic monitoring (real Playwright scripts in prod)          |
  </Tab>

  <Tab title="Observability">
    | Layer                         | Tool                  | Free Tier                 |
    | ----------------------------- | --------------------- | ------------------------- |
    | Error monitoring              | **Sentry**            | 5k errors/mo              |
    | Uptime + status + jobs + logs | **BetterStack**       | 10 monitors, 1 GB logs/mo |
    | Product analytics             | **PostHog**           | 1M events/mo              |
    | Heatmaps + session recordings | **Microsoft Clarity** | Free forever              |
  </Tab>

  <Tab title="CRM & Leads">
    | Tool                            | Role                                                                 |
    | ------------------------------- | -------------------------------------------------------------------- |
    | **AiSensy**                     | WhatsApp lead management — shared team inbox, Meta Click-to-WhatsApp |
    | **Meta Pixel**                  | Browser-side event tracking                                          |
    | **Meta Conversions API (CAPI)** | Server-side event tracking — reliable, unaffected by iOS privacy     |
    | **Custom `/admin/leads`**       | In-house lead pipeline — reads directly from Neon DB                 |

    <Info>
      **Why no external CRM:** all customer and booking data lives in Neon DB. An external CRM would require a continuous sync pipeline, creating two sources of truth. The CRM is built as admin views inside the app.
    </Info>
  </Tab>
</Tabs>

## Design Principles

* **Lighthouse gates:** performance ≥ 95; accessibility, best practices, and SEO = 100
* **Premium feel** — rich, high-end aesthetic matching the brand
* **Edge-first** — sub-100ms response times globally via Cloudflare
* **Single developer** — tooling must minimise ops overhead
* **₹0/month at launch** — every service on a free tier

## Technology Decision Log

Key decisions where alternatives were seriously considered. Expand each to see what was rejected and why.

<AccordionGroup>
  <Accordion title="Auth → Better Auth (rejected: Clerk, Auth.js)">
    Self-hosted, the Google consent screen shows **your** domain, and it ships a built-in RBAC plugin. Clerk and Auth.js were rejected on hosting/branding and missing native RBAC.
  </Accordion>

  <Accordion title="ORM → Drizzle (rejected: Prisma)">
    Prisma's query-engine binary can't run on the Cloudflare Workers V8 isolate without paid Accelerate. Drizzle is pure TypeScript and runs everywhere.
  </Accordion>

  <Accordion title="Database → Neon (rejected: Supabase, PlanetScale)">
    Git-like branching (10 free branches), serverless scale-to-zero, and all scheduled work driven via QStash HTTP routes.
  </Accordion>

  <Accordion title="Hosting → Cloudflare Workers (rejected: Vercel)">
    Cloudflare Workers via the OpenNext adapter (`@opennextjs/cloudflare`) — generous free tier with no bandwidth surprises, plus R2, KV, and Workers all under one roof.
  </Accordion>

  <Accordion title="Realtime → Ably (rejected: Pusher)">
    6M messages/mo free versus Pusher's 200k/day.
  </Accordion>

  <Accordion title="Analytics → PostHog (rejected: Google Analytics)">
    DPDP Act concerns with GA. PostHog offers 1M events/mo plus feature flags.
  </Accordion>

  <Accordion title="Linting → Biome (rejected: ESLint + Prettier)">
    \~100x faster, a single config file, and native TypeScript support.
  </Accordion>
</AccordionGroup>

## Related Pages

<Columns cols={2}>
  <Card title="Architecture" href="/docs/architecture">
    How these technologies fit together as a layered monorepo
  </Card>

  <Card title="Data Model" href="/docs/data-model">
    The 38-table Drizzle schema running on Neon
  </Card>

  <Card title="System Design" href="/docs/system-design">
    High-level and low-level design documents
  </Card>
</Columns>


## Related topics

- [Architecture](/content/docs/architecture.md)
- [Frontend](/content/docs/frontend.md)
- [Getting Started](/content/docs/getting-started.md)
- [Overview](/content/docs/index.md)
- [High-Level Design](/content/docs/system-design/high-level-design.md)