---
title: "Performance Optimization Patterns"
description: "Verified caching layers — React cache(), Next 16 Cache Components, client bootstrap single-flight, and DatabaseService EntityCache."
locale: "en"
---
# Performance Optimization Patterns

Ring Platform optimizes at four layers: **Server Component request dedup**, **Next 16 `'use cache'` catalog reads**, **client bootstrap single-flight**, and **DatabaseService EntityCache**. All patterns below trace to real files — no fabricated KPIs or invented utilities.

> **Info**
> Use **Founder** / **Developer** tabs in the docs sidebar to filter this page.

### For founders

## What keeps your clone fast

Most Ring pages are **React Server Components** — HTML arrives pre-rendered with minimal client JavaScript. Performance wins come from architecture, not bolt-on CDN tricks:

| Layer | Benefit for operators |
|-------|----------------------|
| Server-first rendering | Marketing and catalog pages ship without heavy JS bundles |
| Request-level dedup | One database read per page render, not one per component |
| Batched analytics | Web Vitals sent as one POST per page load, not five |
| Provider SSOT | No duplicate credit-balance or notification polls draining API quota |
| Build-time Firebase mock | Static generation does not require live Firebase credentials |

  
- **[Development performance](/docs/development/performance.md)** — Integrator-focused patterns, pool rules, and SSOT script.

  
- **[Deployment performance](/docs/deployment/performance.md)** — Production hardening and infrastructure tuning.

### For developers

## Caching strategy (verified)

| Layer | Scope | Mechanism | SSOT location |
|-------|-------|-----------|---------------|
| React `cache()` | Per-request (server) | Request dedup within one RSC render pass | `lib/services/firebase-service-manager.ts` (`firebase-full` mode) |
| Next 16 `'use cache'` | Cross-request (server) | `cacheTag` + `cacheLife` | `features/store/config.ts` → `getCachedProductCatalog()` |
| EntityCache | 30s TTL (server) | In-memory Map on `entities` collection | `lib/database/DatabaseService.ts` |
| Bootstrap single-flight | Per-tab (client) | Module-scope promise + TTL keyed by `userId` | `hooks/use-vendor-status.ts` (30s), `hooks/use-credit-balance.ts` (5s bootstrap) |
| Session refetch tuning | Per-tab (client) | 15min interval, no focus/offline refetch | `features/auth/components/session-provider.tsx` |
| Web Vitals batching | Per-tab (client) | Buffer + 1.5s debounce → single POST | `components/providers/web-vitals-provider.tsx` |

**Not used:** `sessionStorage` server caches, custom `RingApiClient`, per-metric Web Vitals POST loops, or performance budget enforcement in `next.config.mjs`.

## Server-side patterns

### React 19 `cache()` — request dedup

```typescript
// lib/services/firebase-service-manager.ts (firebase-full mode)
import { cache } from 'react'

export const getCachedDocument = cache(async (collection: string, docId: string) => {
  const db = getAdminDb()
  const doc = await db.collection(collection).doc(docId).get()
  return doc.exists ? doc : null
})
```

Multiple imports of the same document during one Server Component render resolve to **one** Firestore read.

### Store catalog — `'use cache'` SSOT

```typescript
// features/store/config.ts
export async function getCachedProductCatalog(): Promise<StoreProduct[]> {
  'use cache'
  cacheTag('store:products')
  cacheLife('minutes')

  const adapter = await getStoreAdapter()
  return adapter.listProducts()
}
```

Shared by `app/api/store/products/route.ts` and `getStoreProducts` server action. Invalidate with `updateTag('store:products')` after product mutations.

### DatabaseService EntityCache

30-second TTL on `entities` collection for read-after-write consistency. Writes invalidate affected keys automatically.

### DatabaseService contract

```typescript
const result = await db().queryDocs({
  collection: 'entities',
  filters: [{ field: 'status', operator: 'eq', value: 'active' }],
  orderBy: [{ field: 'createdAt', direction: 'desc' }],
  pagination: { limit: 20, offset: 0 },
})
if (!result.success) throw result.error
```

Use `findDocById` for single-document lookups — not `queryDocs` filtered by `id`.

## Client-side SSOT patterns

### Web Vitals — batched POST (not per-metric)

`WebVitalsProvider` buffers `useReportWebVitals` callbacks and flushes **one** `POST /api/analytics/web-vitals` per debounce window (1.5s), shaped to `webVitalsPayloadSchema` in `features/analytics/lib/analytics-db.ts`. Metrics also flush on `visibilitychange` / `pagehide`.

> **Tip**
> `useReportWebVitals` fires once per Core Web Vital (CLS, FCP, LCP, TTFB, INP). Without batching that would be up to five POSTs per page load. The provider collapses them into one request.

### Bootstrap single-flight hooks

Documented in `hooks/HOOKS-README.md` § P4:

- **`useVendorStatus`** — dedupes `GET /api/vendor/status` across sidebar layout remounts.
- **`useCreditBalance`** — bootstrap fetch dedupes across Strict Mode / Suspense remounts; live updates still flow through `CreditBalanceProvider` + tunnel.

Enforce with `./scripts/validate-provider-ssot.sh` (seven gates — see [Best practices](/docs/development/best-practices.md)).

## Build optimization

```typescript
// next.config.mjs (excerpt)
const nextConfig = {
  reactStrictMode: true,
  cacheComponents: true,
}
```

During `next build`, `lib/firebase/build-mock.server.ts` returns mock Firestore/Auth instances so static generation does not require live Firebase credentials. SWC minification and CSS optimization are handled by Next.js 16 automatically — there is no `swcMinify` or `experimental.optimizeCss` flag.

### Firebase debug metrics (dev only)

`getCacheMetrics()` in `firebase-service-manager.ts` logs hit rate when `FIREBASE_DEBUG_LOGS=true`. This is a **dev console tool**, not production monitoring.

## PostgreSQL pool

All connection pooling lives in `lib/database/`. Domain code uses `db()`; PostGIS-only raw SQL uses `getSharedPgPool()`. Never instantiate `new Pool(` outside `lib/database/` — gate 7 of the SSOT script.

## Related documentation