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

# Architecture

> High-level architecture of the Royal Glow Salon & Spa platform.

# Architecture

<Info>
  Royal Glow is a **monolithic modular** monorepo, not microservices. Strict layer boundaries give the modularity of microservices without the ops burden — and three hard conventions hold everywhere: **money is integer paise**, **IDs are app-generated text**, and **business logic never imports the database or framework**.
</Info>

## Layered monorepo

The Bun + Turborepo workspace holds four apps/packages workspaces:

| Name              | Type                    | Description                                                              |
| ----------------- | ----------------------- | ------------------------------------------------------------------------ |
| `@rgss/web`       | `theroyalglow.in`       | Customer Next.js site — Cloudflare Worker rgss-web (dev port 3000).      |
| `@rgss/admin`     | `admin.theroyalglow.in` | Admin portal Next.js app — Cloudflare Worker rgss-admin (dev port 3001). |
| `@rgss/cms`       | `cms.theroyalglow.in`   | Payload CMS v3 — Render service rgss-cms (dev port 3002).                |
| `@rgss/invoicing` | `Cloud Run`             | PDF invoice render service.                                              |

The codebase enforces a strict dependency direction so business rules stay
testable and framework-agnostic. Each layer may only import inward.

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

<Warning>
  **API routes are thin orchestrators:** parse → validate with Zod → call business logic → return JSON. No database queries live in route handlers.
</Warning>

## Hosting topology

The platform spans a Render origin and a Cloud Run service, backed by Neon, and is migrating to AWS. Pick a concern below.

<Tabs>
  <Tab title="Web & Admin">
    The customer site (`rgss-web`) and admin portal (`rgss-admin`) are Next.js 16 App Router apps
    served as Node servers (`next build` + `next start`) on **Render**, with the service catalogue
    cached in Redis (5-min TTL).

    The target is **AWS Lambda + CloudFront**, deployed with SST (which wraps OpenNext): an ARM64 SSR
    function and a CloudFront distribution per app, in `ap-southeast-1` beside the Neon database. Only
    these two apps move — the CMS stays on Render and every managed dependency stays put, so no
    application code changes. See `M2AWS.md`.

    Cloudflare Workers via OpenNext was the original plan and is **retired** — the Worker bundle
    exceeded Cloudflare's free-plan script size limit, and the adapter has been removed from the repo.
  </Tab>

  <Tab title="Origin & CMS">
    **Render (Singapore)** hosts the **Payload CMS** (`rgss-cms`) — a Node.js runtime, closest free region to India. The **`@rgss/invoicing`** PDF render service runs on **Cloud Run**.
  </Tab>

  <Tab title="Database">
    A single **Neon** project with four branches (`prod`, `pprd`, `test`, `dev`). The CMS owns its own tables, disjoint from the app's Drizzle schema.
  </Tab>

  <Tab title="Media & Queue">
    **Cloudflare R2** for media (S3-compatible, zero egress). **Upstash Redis + QStash** for cache and queue. **Ably** for realtime.
  </Tab>
</Tabs>

## Observability

Five layers, each on a free tier.

| Name                | Type                | Description                                    |
| ------------------- | ------------------- | ---------------------------------------------- |
| `Sentry`            | `errors`            | Application + Worker error monitoring.         |
| `BetterStack`       | `uptime`            | Uptime, status page, job heartbeats, and logs. |
| `PostHog`           | `product analytics` | Product analytics plus feature flags.          |
| `Microsoft Clarity` | `UX`                | Heatmaps and session replay.                   |
| `Checkly`           | `synthetic`         | Synthetic browser monitoring.                  |

All third-party browser scripts load only after explicit cookie consent and only when their keys are configured.

## Conventions

<Info>
  These hold across the whole monorepo and are covered in depth on the [Conventions](/docs/conventions) page.
</Info>

* Money is stored as integer **paise**; never floating point.
* Timestamps are `timestamptz` (stored UTC, displayed IST).
* Dates display as DD/MM/YYYY and currency in Indian grouping (₹1,00,000.00).
* Every external integration is a guarded extension point: with no key
  configured it no-ops and logs, so the whole monorepo builds and runs locally
  without secrets.

## Related Pages

<Columns cols={2}>
  <Card title="Conventions" href="/docs/conventions">
    Money, dates, layering, and the API response envelope
  </Card>

  <Card title="Tech Stack" href="/docs/tech-stack">
    Every technology and why it was chosen
  </Card>

  <Card title="System Design" href="/docs/system-design">
    Formal HLD and LLD documents
  </Card>
</Columns>


## Related topics

- [High-Level Design](/content/docs/system-design/high-level-design.md)
- [System Design](/content/docs/system-design/index.md)
- [Frontend](/content/docs/frontend.md)
- [Deployment](/content/docs/deployment.md)
- [Low-Level Design](/content/docs/system-design/low-level-design.md)