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

# System Design

> High-level and low-level design documents for the Royal Glow platform.

# System Design

This section contains the formal system design documentation for the Royal Glow Salon & Spa platform — written to staff-engineer review standard.

<Info>
  Royal Glow is a **monolithic modular** monorepo targeting 20k–50k registered users at **₹0/month** infrastructure cost. Read the High-Level Design for architecture and decisions; the Low-Level Design for state machines, sequences, and schema detail.
</Info>

## Documents

<Columns cols={2}>
  <Card title="High-Level Design" href="/docs/system-design/high-level-design">
    Architecture overview, technology decisions, data model, auth design, and API patterns.
  </Card>

  <Card title="Low-Level Design" href="/docs/system-design/low-level-design">
    Database schema details, state machines, sequence diagrams, and implementation specifics.
  </Card>
</Columns>

## At a Glance

| Name                          | Type                 | Description                                                      |
| ----------------------------- | -------------------- | ---------------------------------------------------------------- |
| `Application routes`          | `~104 pages`         | Customer (web), admin (incl. staff self-service), and API layers |
| `Database tables`             | `38`                 | Across 15 Drizzle schema files                                   |
| `API endpoints`               | `~90 route handlers` | Thin orchestrators across web + admin + jobs                     |
| `Background jobs`             | `19`                 | 14 scheduled + 4 triggered + 1 GitHub Actions                    |
| `Registered users (target)`   | `20,000–50,000`      | Future-proof scale target                                        |
| `Concurrent users (peak)`     | `50`                 | Load-test target on pprd                                         |
| `Monthly infrastructure cost` | `₹0`                 | All free tiers at launch                                         |

## Architecture Style

**Monolithic modular architecture** — not microservices.

The codebase uses strict layer separation within a monorepo to achieve the modularity benefits of microservices without the operational burden. Each layer has explicit import boundaries enforced by the package structure.

```text theme={null}
Presentation → API (thin) → Business Logic → Data Access → Database
```

No database queries in API routes. No framework dependencies in business logic. No I/O in pure functions.

## Key Design Decisions

<AccordionGroup>
  <Accordion title="Architecture → Monolithic modular">
    Solo developer — there are no team boundaries to split a microservice topology along. Strict layers give the modularity without the ops cost.
  </Accordion>

  <Accordion title="Database → Neon PostgreSQL">
    Git-like branching, serverless scale-to-zero, and a generous free tier.
  </Accordion>

  <Accordion title="ORM → Drizzle">
    Pure TypeScript — runs on the Cloudflare Workers V8 isolate where Prisma's binary cannot.
  </Accordion>

  <Accordion title="Auth → Better Auth">
    Self-hosted, Google OAuth with your own domain on the consent screen, and built-in RBAC.
  </Accordion>

  <Accordion title="Edge → Cloudflare Workers (OpenNext)">
    Global edge delivery with a generous free tier. Both Next.js apps deploy to Cloudflare Workers via the OpenNext adapter (`@opennextjs/cloudflare`) — not Pages.
  </Accordion>

  <Accordion title="Realtime → Ably">
    6M messages/mo free, with Token Auth for per-role channel scoping.
  </Accordion>

  <Accordion title="Money → integer paise">
    Eliminates floating-point rounding errors in billing and GST.
  </Accordion>

  <Accordion title="IDs → nanoid() text">
    App-generated text keys prevent enumeration attacks.
  </Accordion>
</AccordionGroup>


## Related topics

- [System Design](/content/docs/system-design/index.md)
- [Tech Stack](/content/docs/tech-stack.md)
- [Architecture](/content/docs/architecture.md)
- [Overview](/content/docs/index.md)
- [High-Level Design](/content/docs/system-design/high-level-design.md)