# Caching strategy (Ghabilee)

**Audience:** humans and coding agents working on قبیله frontend/backend.

**Last updated:** 2026-08-31

This document is the **source of truth** for how we cache public (guest) traffic
vs authenticated (logged-in) traffic. Read it before changing SSR, `fetch`
options, `revalidate`, cookies on public pages, or discovery Redis TTLs.

Related (narrower scope):

- Client-side TanStack Query: [`consumer-caching.md`](./consumer-caching.md)
- Admin lists: [`admin-caching.md`](./admin-caching.md)
- Server `fetch` helpers: [`lib/seo/serverApi.ts`](../lib/seo/serverApi.ts)
- Backend Redis namespaces: [`backend/src/modules/events/discovery-reference.constants.ts`](../../backend/src/modules/events/discovery-reference.constants.ts)

---

## 1. Two user models — two strategies

| User model                | Phase-1 volume | Goal                       | Strategy                                               |
| ------------------------- | -------------- | -------------------------- | ------------------------------------------------------ |
| **Guest** (not logged in) | Very high      | Fast TTFB, low server cost | **Shared HTML (ISR)** + Data Cache + Redis             |
| **Logged in**             | Lower          | Correct personalized UX    | **Dynamic SSR/CSR** + TanStack Query (data cache only) |

**Rule of thumb**

> If the response depends on session / JWT / user id → **never** put it in Full Route Cache (shared HTML).
>
> If the response is the same for every guest → **prefer ISR** (shared HTML) with a short `revalidate`.

Guests browse nationwide events, city landings, event detail, SEO pages.
Logged-in users use profile, bookings, chats, my-events — speed of first HTML
byte is less important than correctness.

---

## 2. Cache layers (top to bottom)

```
Browser
  └─ TanStack Query (logged-in + client refinements)     ← per-tab, in-memory
Nginx (host edge)
  └─ proxy_cache for guest HTML document GETs            ← shared across guests (P2)
Next.js server
  └─ Full Route Cache (ISR / static HTML)                ← shared across guests
  └─ Data Cache (`fetch` + `next.revalidate`)            ← shared across all SSR
Backend (NestJS)
  └─ Redis (`PublicCacheService`)                        ← shared across all API callers
PostgreSQL
  └─ source of truth
```

### 2.1 Full Route Cache (HTML)

- **What:** Pre-rendered HTML for a route segment, reused for many requests until `revalidate` expires.
- **Who benefits:** Guests hitting high-traffic public routes.
- **What breaks it:** Dynamic APIs in that segment — `cookies()`, `headers()`, `searchParams` (unstable), `noStore()`, `cache: 'no-store'`.
- **Our choice:** Guest public pages use `export const revalidate = N`. Logged-in app surfaces stay dynamic.

### 2.2 Data Cache (Next `fetch`)

- **What:** Cached JSON responses from `fetch(url, { next: { revalidate: N } })`.
- **Who benefits:** Every SSR request (guest ISR rebuilds and dynamic logged-in pages).
- **Independent of** per-user HTML: even when HTML is rebuilt per request, **fetch results are shared** across users until TTL.

Implemented in `lib/seo/serverApi.ts` → `publicGet()`.

### 2.3 TanStack Query (browser)

- **What:** In-memory client cache after hydration; keys from `queries/consumerKeys.ts`.
- **Who benefits:** Logged-in flows, tab keep-alive, soft navigation, filter changes.
- **Not** a substitute for guest HTML ISR — guests often leave before hydration matters for repeat visits.

See [`consumer-caching.md`](./consumer-caching.md).

### 2.4 Backend Redis

- **What:** `PublicCacheService.getOrSet()` for `@Public()` discovery endpoints.
- **Namespaces:** `discovery-cities`, `discovery-categories`, `discovery-home-feed`, etc.
- **TTL:** Reference data = permanent until admin invalidation; home-feed = **30s**.

Even if Next Data Cache misses, Redis avoids hitting Postgres on every API call.

`PublicCacheService` protects cache misses at two levels: an in-process
single-flight map and a short Redis `SET NX` lease shared by all backend
instances. The lease owner double-checks the cache before calling the factory;
waiters consume its result, with a bounded fail-open timeout. Cache writes are
conditional on the namespace version observed before the factory ran, so a
slow request cannot repopulate an invalidated generation.

Permanent-entry invalidation is one atomic Redis Lua operation: it deletes the
old-generation key and advances the namespace version together. Do not replace
it with a separate `DEL` followed by `INCR`; that ordering can leave a
concurrently rewritten, non-expiring orphan key.

### 2.5 Nginx edge HTML cache (P2)

Guest **document** GETs for ISR routes are cached on the VPS Nginx layer
**before** Next.js. This is the fastest layer for repeat guest traffic.

| Item              | Value                                                              |
| ----------------- | ------------------------------------------------------------------ |
| Config            | `deploy/nginx/conf.d/ghabilee-public-html-cache.conf`              |
| Locations         | `deploy/nginx/snippets/ghabilee-public-html-locations.conf` (prod) |
| Install script    | `scripts/nginx-install-public-html-cache.sh`                       |
| Cache dir         | `/var/cache/nginx/ghabilee_public_html`                            |
| Diagnostic header | `X-Ghabilee-Cache: HIT \| MISS \| BYPASS \| …`                     |

**Cached paths (GET/HEAD only)**

| Path pattern                                                  | Edge TTL | Matches Next ISR |
| ------------------------------------------------------------- | -------- | ---------------- |
| `/`                                                           | 60s      | 60s              |
| `/e/[slug]`                                                   | 60s      | 60s              |
| `/city/**`                                                    | 300s     | 300s             |
| `/category/**`                                                | 300s     | 300s             |
| `/blog/**`                                                    | 300s     | 300s             |
| `/about`, `/contact`, `/become-a-host`                        | 1d       | 1d (`86400s`)    |
| `/faq`, `/terms`, `/privacy`, `/refund-policy`, `/host-guide` | 1d       | 1d (`86400s`)    |

**Never edge-cached (bypass rules)**

- Non-GET/HEAD, WebSocket `Upgrade`
- Next.js RSC / soft-nav (`RSC` header, `_rsc=` query, `Next-Router-State-Tree`, `Accept: text/x-component`)
- All other routes (`/profile`, `/api`, `/_next/*` via catch-all) — unchanged

Logged-in users may receive cached **guest** HTML for these URLs; client-side
auth refine is intentional (see §1).

**Next.js `Cache-Control`:** ISR guest pages still arrive from Next with
`private, no-store` because `app/layout.tsx` reads CSP nonce headers. Nginx
uses `proxy_ignore_headers Cache-Control` on these locations so edge TTL is
controlled by `proxy_cache_valid`, then rewrites browser `Cache-Control` with
`s-maxage` aligned to ISR.

**CSP nonce note:** Edge-cached HTML reuses the same nonce body+header pair for the cache TTL. This is an
accepted trade-off for guest throughput; do not edge-cache personalized routes.

Static assets (`/_next/static`, `/uploads/`): long `Cache-Control` in
`deploy/nginx/ghabile.conf` (separate from this HTML zone).

**VPS rollout** (after merging nginx changes):

```bash
cd /opt/ghabilee
git pull
sudo ./scripts/nginx-install-public-html-cache.sh
sudo cp deploy/nginx/ghabile.conf /etc/nginx/sites-available/ghabilee
sudo nginx -t && sudo systemctl reload nginx
curl -sSI https://ghabilee.ir/ | grep -i x-ghabilee-cache   # expect MISS then HIT
```

---

## 3. Route inventory

### 3.1 Guest — ISR (shared HTML)

| Route                     | File                                  | `revalidate` | Notes                                                                          |
| ------------------------- | ------------------------------------- | ------------ | ------------------------------------------------------------------------------ |
| `/` home                  | `app/(consumer)/page.tsx`             | **60s**      | Nationwide `home-feed` SSR; **no `cookies()`** on this page                    |
| `/e/[slug]` event landing | `app/(seo)/e/[slug]/page.tsx`         | 60s          | Hard load + SEO; soft-nav uses client overlay                                  |
| `/city/[slug]`            | `app/(seo)/city/[slug]/page.tsx`      | 300s         |                                                                                |
| `/category/**`            | `app/(seo)/category/**`               | 300s         |                                                                                |
| `/blog/**`                | `app/(public)/blog/**`                | 300s         |                                                                                |
| `/about`                  | `app/(public)/about/page.tsx`         | **86400s**   | Static marketing copy                                                          |
| `/contact`                | `app/(public)/contact/page.tsx`       | **86400s**   | Static shell; form POST is client/API                                          |
| `/become-a-host`          | `app/(public)/become-a-host/page.tsx` | **86400s**   | Static marketing copy                                                          |
| `/faq`, `/terms`, …       | `app/(public)/[infoPage]/page.tsx`    | **86400s**   | `PUBLIC_PAGE_SLUGS` in `content/publicPages.ts` — **sync nginx regex** (below) |

**Static info pages (`PUBLIC_PAGE_SLUGS`) — keep nginx in sync**

`app/(public)/[infoPage]/page.tsx` only generates routes for slugs in
`PUBLIC_PAGE_SLUGS` (`frontend/content/publicPages.ts`). Nginx does **not**
read that list — the 1-day edge-cache regex is **hard-coded** in:

- `deploy/nginx/snippets/ghabilee-public-html-locations.conf` (production)
- `deploy/nginx/snippets/ghabilee-public-html-locations.dev.conf` (staging)

When you **add or rename** a slug in `PUBLIC_PAGE_SLUGS`, you must also update
the alternation in both files, for example:

```nginx
location ~ ^/(?:about|contact|become-a-host|faq|terms|privacy|refund-policy|host-guide|NEW-SLUG)$ {
```

Then on the VPS: copy snippets + `nginx -t && systemctl reload nginx` (see §2.5).
Forgetting this step means the new page works in Next but **misses edge HTML cache**.

Dedicated routes `/about`, `/contact`, `/become-a-host` are listed explicitly in
that regex — they are not driven by `PUBLIC_PAGE_SLUGS`.
| `/u/[slug]` | `app/(public)/**` | 300s | |

### 3.2 Guest — dynamic by design

| Surface                                       | Why dynamic                                                      |
| --------------------------------------------- | ---------------------------------------------------------------- |
| Soft-nav event overlay `@modal/(...)e/[slug]` | Client intercept; not a full document navigation                 |
| `TrafficAttributionBeacon`                    | Wrapped in `<Suspense>` on home; attribution POST is client-side |

### 3.3 Logged-in — dynamic + TanStack Query

All under `app/(consumer)/` except the **guest-shared** home ISR shell:

- `/profile`, `/bookings`, `/chats`, `/my-events`, `/identity`, …
- Host wizard `app/events/**` (uses `cookies()` for token)
- After login, home **refines** feed client-side (`ConsumerHomeDiscovery` + `useViewerDiscoveryCityId`)

**Do not** add `export const revalidate` to these routes.

### 3.4 Root layout caveat

`app/layout.tsx` reads `headers()` for CSP nonce → opts the **root layout** into
dynamic rendering. **Child segments can still use ISR** when they export
`revalidate` and avoid `cookies()` / `headers()` in their own segment. This is
why `/e/[slug]` ISR works today.

**Agents:** do not remove the root `headers()` call without a security review.
Fix caching at the **page segment** that serves guests, not by weakening CSP.

---

## 4. Home page (`/`) — detailed contract

### 4.1 SSR payload (same for every guest)

Server component `app/(consumer)/page.tsx` fetches in parallel:

1. `fetchDiscoveryCities()` — Data Cache 5 days
2. `fetchDiscoveryCategories()` — Data Cache 5 days
3. `fetchDiscoveryHomeFeed()` — **nationwide** (no `cityId`), Data Cache 60s

Passed as props to `ConsumerHomeDiscovery`:

- `initialCategories`, `initialCities`, `initialHomeFeed`, error props

### 4.2 Client refinements

`ConsumerHomeDiscovery` (`app/(consumer)/_components/ConsumerHomeDiscovery.tsx`):

| Concern                       | Guest                                                            | Logged in              |
| ----------------------------- | ---------------------------------------------------------------- | ---------------------- |
| Popular + category feed scope | Nationwide (`feedCityId = undefined`)                            | Profile city when set  |
| Feed query                    | `placeholderData` from SSR nationwide feed while city feed loads | Same pattern           |

### 4.3 Revalidate alignment

| Layer                                 | TTL                         |
| ------------------------------------- | --------------------------- |
| Page ISR (`export const revalidate`)  | 60                          |
| `fetchDiscoveryHomeFeed` Data Cache   | 60                          |
| Backend Redis `discovery-home-feed`   | 30                          |
| TanStack `discoveryHomeFeedStaleTime` | see `services/discovery.ts` |

When debugging stale home events, check all three layers plus admin event publish.

---

## 5. Event detail — two entry paths

| Entry                        | Path                             | Caching                                      |
| ---------------------------- | -------------------------------- | -------------------------------------------- |
| Hard load / share link / SEO | `(seo)/e/[slug]/page.tsx`        | ISR 60s + `fetchPublicEventLandingBootstrap` |
| Soft-nav from home shell     | `@modal/(...)e/[slug]` intercept | Client fetch; overlay UI                     |

Agents adding event UI must consider **both** paths or document which is in scope.

---

## 6. What agents must / must not do

### Must

- Keep **guest marketing data** on `@Public()` API routes with Redis caching.
- Use `lib/seo/serverApi.ts` for server components — not `@/config/axios`.
- Use `export const revalidate` on new **guest** indexable landings.
- Gate TanStack `initialData` from SSR to the **exact** key the server fetched (see `ConsumerHomeDiscovery` `useSsrFeed` guard).
- Invalidate backend discovery cache when admin mutates cities/categories/events (existing `invalidatePermanentEntry` patterns).
- When changing `PUBLIC_PAGE_SLUGS`, update nginx static-marketing regex in both `ghabilee-public-html-locations*.conf` files (§3.1).

### Must not

- Call `cookies()` or `headers()` in guest ISR pages to read preferences (city, locale, A/B). Read them **client-side** instead.
- Use `cache: 'no-store'` on public discovery `fetch` without explicit approval.
- Assume Data Cache = HTML Cache — they are separate.
- Add Full Route Cache to `/profile`, `/bookings`, or any JWT-scoped page.

### When adding a new public page

1. Classify: guest-shared vs session-personalized.
2. Guest-shared → `revalidate` + `serverApi` fetch with TTL (or static copy → `86400` for marketing/legal).
3. Session-personalized → dynamic + consumer query hooks.
4. Update the **route inventory** table in this doc (section 3).
5. **If the page is a new `[infoPage]` slug:** append the slug to the nginx
   static-marketing `location` regex in **both**
   `ghabilee-public-html-locations.conf` and `ghabilee-public-html-locations.dev.conf`
   (see §3.1 — `PUBLIC_PAGE_SLUGS` sync). Reload nginx on the VPS after deploy.

---

## 7. Implementation priorities

| Priority | Work                                                                                | Status                                                                        |
| -------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **P0**   | ISR `/` — remove `cookies()` from `page.tsx`, `revalidate = 60`                     | Done (2026-08-31)                                                             |
| **P1**   | Ensure guest event views hit ISR route on hard load (already `/e/[slug]`)           | Done                                                                          |
| **P2**   | Nginx edge HTML cache for guest ISR routes                                          | Config in repo — **activate on VPS** via `nginx-install-public-html-cache.sh` |

---

## 8. Debugging checklist

**"Guest home shows old events"**

1. Page ISR age (up to 60s)
2. Next Data Cache for `discovery/home-feed` (60s)
3. Redis `discovery-home-feed` (30s)
4. Event discoverability flags in DB

**"Second guest isn't faster"**

1. Confirm route is ISR (`revalidate` exported, no `cookies()` in page)
2. Check `X-Ghabilee-Cache` header — `HIT` means Nginx edge served HTML
3. Check server logs — Next miss should not call API if Data Cache warm
4. Distinguish TTFB (HTML) vs client hydration

**"Logged-in user sees wrong city on home"**

1. `useViewerDiscoveryCityId` / profile `cityId`
2. `consumerKeys.discoveryHomeFeed(feedCityKey)` — not SSR `initialData` on city key
3. `placeholderData` vs `initialData` rules in `ConsumerHomeDiscovery`

---

## 9. Glossary

| Term                   | Meaning                                                               |
| ---------------------- | --------------------------------------------------------------------- |
| **ISR**                | Incremental Static Regeneration — shared HTML with timed revalidation |
| **Full Route Cache**   | Next.js cache of rendered route output (HTML + RSC payload)           |
| **Data Cache**         | Next.js cache of `fetch` responses                                    |
| **Nationwide feed**    | `home-feed` without `cityId` — marketing default for guests           |