Best Practices

Development patterns and conventions specific to Ring Platform v1.6.4.

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

Development principles

Quality over quantity

Ring Platform is a multi-tenant white-label platform powering production clones. Every pattern must work across PostgreSQL-primary (k8s-postgres-fcm) and Firebase-backed deployments. The DatabaseService abstraction ensures this — write to db() once, run anywhere.

Security by convention

userId is always derived from await auth() in server code, never from client-supplied parameters.
Payment operations run server-side only. WayForPay HMAC signatures verify callback authenticity.
File uploads go through file() abstraction (@/lib/file) — access controls are enforced at the upload layer.

i18n is not optional

All user-facing strings live in locales/{locale}/ JSON bundles loaded by next-intl. See Proxy and i18n.

Respect the backend mode

DB_BACKEND_MODE selects the database adapter at runtime. Do not import firebase-admin or postgres directly in domain code. See Backend modes and databases.

Database access

The `db()` singleton

The primary database interface is db() from @/lib/database. It auto-initializes and provides typed *Doc methods returning { success, data, error }.

The db() singleton survives Next.js dev HMR via globalThis.__ringDatabaseService. Collections map to PostgreSQL tables through PostgreSQLAdapter field mappings in lib/database/adapters/PostgreSQLAdapter.ts — aligned with data/schema.sql. Do not assume ad-hoc table names; use the collection keys the adapter routes (e.g. platform_settings, entities, users).

`platform_settings` and namespaced config

Platform-wide settings (AI matcher, branding, feature flags) persist in the platform_settings collection/table. Access via db() — not raw SQL:

Secrets columns are masked in admin GET handlers; never embed production keys in MDX or client bundles.

PostGIS escape hatch only

For spatial queries the doc-model cannot express, use the shared pool:

getSharedPgPool() in lib/database/shared-pg-pool.ts returns the connected PostgreSQLAdapter pool after initializeDatabase(). new Pool( is allowed only under lib/database/ — the SSOT script enforces this.

Transactions

Use db().transaction() for atomic multi-step writes. Errors throw inside the callback.

Do not use raw Firestore or pg queries in feature code except PostGIS via getSharedPgPool(). Every other database operation goes through DatabaseService so backends can switch without rewriting business logic.

Provider SSOT script

scripts/validate-provider-ssot.sh gates duplicate-fetch regressions. Run before merging provider or hook changes:

#	Gate	Rule
1	`useUnreadCount`	Allowed only in `notification-provider`, `use-unread-count.ts`, tests
2	`useCreditBalance(`	Allowed only in `credit-balance-provider`, `use-credit-balance.ts`, tests
3	`useCreditHistory(`	Allowed only in `credit-history-provider`, `use-credit-history.ts`, `wallet-wrapper`, tests
4	`fetch('/api/vendor/status')`	Allowed only in `hooks/use-vendor-status.ts`
5	`'/api/wallet/credit/balance'`	Allowed only in `hooks/use-credit-balance.ts`
6

Client single-flight pattern

When a hook performs a one-shot bootstrap fetch (not a long-lived subscription), use module-scope single-flight + short TTL keyed by userId:

Hook	TTL	Endpoint
`use-vendor-status.ts`	30s	`GET /api/vendor/status`
`use-credit-balance.ts` (bootstrap only)	5s	`GET /api/wallet/credit/balance`

Pattern: check cache → return in-flight promise → fetch → store. Manual refresh() bypasses bootstrap cache. See hooks/HOOKS-README.md § P4.

Provider-owned streams (unread count, credit balance live updates) still use context — single-flight is for deduping mount-time duplicates, not replacing providers.

Server Actions

All Server Actions live in app/_actions/.

File-level 'use server' at the top.
import { auth } from '@/auth' — never accept userId from the client.
Return form-state objects { success?, error?, message? }.
Use localizedRedirect for navigation after success.
Zod or manual validation at the boundary.

See app/_actions/vendor-actions.ts for file uploads via file(), nested create + update, and multi-step onboarding.

Authentication

Server-side

Client-side

Canonical config: root auth.ts. Session wrapper: features/auth/components/session-provider.tsx with refetchInterval={15 * 60}, refetchOnWindowFocus={false}, refetchWhenOffline={false}.

Never pass userId from the client to a Server Action or API route. See app/_actions/fcm.ts for the canonical pattern.

Server vs client boundaries

Default to Server Components — fetch via services or db() on the server.
Push client boundaries down — forms, maps, realtime leaves only.
Avoid useEffect for data fetching — prefer Server Actions, Route Handlers, or useActionState.

File uploads

Testing

Tests live in __tests__/. Mock at boundaries (constants, next/link, i18n) — do not mock @/lib/database with fake Firestore for unit tests. See Testing guide.

Code organization

Path	Purpose
`app/_actions/`	Server Actions, one file per domain
`features/{domain}/services/`	Business logic callable from actions or routes
`lib/database/`	Database abstraction — no feature-specific queries
`components/`	Shared UI; feature components in `features/{domain}/components/`

See Code structure for provider matrix and P4 hooks.

Best Practices

Development patterns and conventions specific to Ring Platform v1.6.4.

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

Development principles

Quality over quantity

Security by convention

userId is always derived from await auth() in server code, never from client-supplied parameters.
Payment operations run server-side only. WayForPay HMAC signatures verify callback authenticity.
File uploads go through file() abstraction (@/lib/file) — access controls are enforced at the upload layer.

i18n is not optional

All user-facing strings live in locales/{locale}/ JSON bundles loaded by next-intl. See Proxy and i18n.

Respect the backend mode

DB_BACKEND_MODE selects the database adapter at runtime. Do not import firebase-admin or postgres directly in domain code. See Backend modes and databases.

Database access

The `db()` singleton

The primary database interface is db() from @/lib/database. It auto-initializes and provides typed *Doc methods returning { success, data, error }.

`platform_settings` and namespaced config

Platform-wide settings (AI matcher, branding, feature flags) persist in the platform_settings collection/table. Access via db() — not raw SQL:

Secrets columns are masked in admin GET handlers; never embed production keys in MDX or client bundles.

PostGIS escape hatch only

For spatial queries the doc-model cannot express, use the shared pool:

Transactions

Use db().transaction() for atomic multi-step writes. Errors throw inside the callback.

Provider SSOT script

scripts/validate-provider-ssot.sh gates duplicate-fetch regressions. Run before merging provider or hook changes:

#	Gate	Rule
1	`useUnreadCount`	Allowed only in `notification-provider`, `use-unread-count.ts`, tests
2	`useCreditBalance(`	Allowed only in `credit-balance-provider`, `use-credit-balance.ts`, tests
3	`useCreditHistory(`	Allowed only in `credit-history-provider`, `use-credit-history.ts`, `wallet-wrapper`, tests
4	`fetch('/api/vendor/status')`	Allowed only in `hooks/use-vendor-status.ts`
5	`'/api/wallet/credit/balance'`	Allowed only in `hooks/use-credit-balance.ts`
6

Client single-flight pattern

When a hook performs a one-shot bootstrap fetch (not a long-lived subscription), use module-scope single-flight + short TTL keyed by userId:

Hook	TTL	Endpoint
`use-vendor-status.ts`	30s	`GET /api/vendor/status`
`use-credit-balance.ts` (bootstrap only)	5s	`GET /api/wallet/credit/balance`

Pattern: check cache → return in-flight promise → fetch → store. Manual refresh() bypasses bootstrap cache. See hooks/HOOKS-README.md § P4.

Provider-owned streams (unread count, credit balance live updates) still use context — single-flight is for deduping mount-time duplicates, not replacing providers.

Server Actions

All Server Actions live in app/_actions/.

File-level 'use server' at the top.
import { auth } from '@/auth' — never accept userId from the client.
Return form-state objects { success?, error?, message? }.
Use localizedRedirect for navigation after success.
Zod or manual validation at the boundary.

See app/_actions/vendor-actions.ts for file uploads via file(), nested create + update, and multi-step onboarding.

Authentication

Server-side

Client-side

Canonical config: root auth.ts. Session wrapper: features/auth/components/session-provider.tsx with refetchInterval={15 * 60}, refetchOnWindowFocus={false}, refetchWhenOffline={false}.

Never pass userId from the client to a Server Action or API route. See app/_actions/fcm.ts for the canonical pattern.

Server vs client boundaries

Default to Server Components — fetch via services or db() on the server.
Push client boundaries down — forms, maps, realtime leaves only.
Avoid useEffect for data fetching — prefer Server Actions, Route Handlers, or useActionState.

File uploads

Testing

Tests live in __tests__/. Mock at boundaries (constants, next/link, i18n) — do not mock @/lib/database with fake Firestore for unit tests. See Testing guide.

Code organization

Path	Purpose
`app/_actions/`	Server Actions, one file per domain
`features/{domain}/services/`	Business logic callable from actions or routes
`lib/database/`	Database abstraction — no feature-specific queries
`components/`	Shared UI; feature components in `features/{domain}/components/`

See Code structure for provider matrix and P4 hooks.

Best Practices

Development patterns and conventions specific to Ring Platform v1.6.4.

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

Development principles

Quality over quantity

Security by convention

userId is always derived from await auth() in server code, never from client-supplied parameters.
Payment operations run server-side only. WayForPay HMAC signatures verify callback authenticity.
File uploads go through file() abstraction (@/lib/file) — access controls are enforced at the upload layer.

i18n is not optional

All user-facing strings live in locales/{locale}/ JSON bundles loaded by next-intl. See Proxy and i18n.

Respect the backend mode

DB_BACKEND_MODE selects the database adapter at runtime. Do not import firebase-admin or postgres directly in domain code. See Backend modes and databases.

Database access

The `db()` singleton

The primary database interface is db() from @/lib/database. It auto-initializes and provides typed *Doc methods returning { success, data, error }.

`platform_settings` and namespaced config

Platform-wide settings (AI matcher, branding, feature flags) persist in the platform_settings collection/table. Access via db() — not raw SQL:

Secrets columns are masked in admin GET handlers; never embed production keys in MDX or client bundles.

PostGIS escape hatch only

For spatial queries the doc-model cannot express, use the shared pool:

Transactions

Use db().transaction() for atomic multi-step writes. Errors throw inside the callback.

Provider SSOT script

scripts/validate-provider-ssot.sh gates duplicate-fetch regressions. Run before merging provider or hook changes:

#	Gate	Rule
1	`useUnreadCount`	Allowed only in `notification-provider`, `use-unread-count.ts`, tests
2	`useCreditBalance(`	Allowed only in `credit-balance-provider`, `use-credit-balance.ts`, tests
3	`useCreditHistory(`	Allowed only in `credit-history-provider`, `use-credit-history.ts`, `wallet-wrapper`, tests
4	`fetch('/api/vendor/status')`	Allowed only in `hooks/use-vendor-status.ts`
5	`'/api/wallet/credit/balance'`	Allowed only in `hooks/use-credit-balance.ts`
6

Client single-flight pattern

When a hook performs a one-shot bootstrap fetch (not a long-lived subscription), use module-scope single-flight + short TTL keyed by userId:

Hook	TTL	Endpoint
`use-vendor-status.ts`	30s	`GET /api/vendor/status`
`use-credit-balance.ts` (bootstrap only)	5s	`GET /api/wallet/credit/balance`

Pattern: check cache → return in-flight promise → fetch → store. Manual refresh() bypasses bootstrap cache. See hooks/HOOKS-README.md § P4.

Provider-owned streams (unread count, credit balance live updates) still use context — single-flight is for deduping mount-time duplicates, not replacing providers.

Server Actions

All Server Actions live in app/_actions/.

File-level 'use server' at the top.
import { auth } from '@/auth' — never accept userId from the client.
Return form-state objects { success?, error?, message? }.
Use localizedRedirect for navigation after success.
Zod or manual validation at the boundary.

See app/_actions/vendor-actions.ts for file uploads via file(), nested create + update, and multi-step onboarding.

Authentication

Server-side

Client-side

Canonical config: root auth.ts. Session wrapper: features/auth/components/session-provider.tsx with refetchInterval={15 * 60}, refetchOnWindowFocus={false}, refetchWhenOffline={false}.

Never pass userId from the client to a Server Action or API route. See app/_actions/fcm.ts for the canonical pattern.

Server vs client boundaries

Default to Server Components — fetch via services or db() on the server.
Push client boundaries down — forms, maps, realtime leaves only.
Avoid useEffect for data fetching — prefer Server Actions, Route Handlers, or useActionState.

File uploads

Testing

Tests live in __tests__/. Mock at boundaries (constants, next/link, i18n) — do not mock @/lib/database with fake Firestore for unit tests. See Testing guide.

Code organization

Path	Purpose
`app/_actions/`	Server Actions, one file per domain
`features/{domain}/services/`	Business logic callable from actions or routes
`lib/database/`	Database abstraction — no feature-specific queries
`components/`	Shared UI; feature components in `features/{domain}/components/`

See Code structure for provider matrix and P4 hooks.

Related documentation

Code structure

App Router layout, provider matrix, SessionProvider SSOT path.

Performance

Caching layers, pool rules, SSOT enforcement.

Backend modes

DB_BACKEND_MODE and adapter selection.

Data validation

Zod schemas and API boundaries.

SessionProvider

typescript


import { db } from '@/lib/database'

const result = await db().createDoc('entities', { name: 'Acme', type: 'technology' })
if (!result.success) throw result.error

const entity = await db().findDocById<Entity>('entities', id)
if (!entity.success) throw entity.error

const results = await db().queryDocs<Entity>({
  collection: 'entities',
  filters: [{ field: 'status', operator: '==', value: 'active' }],
  orderBy: [{ field: 'name', direction: 'asc' }],
  pagination: { limit: 20, offset: 0 },
})

typescript


import { getSharedPgPool } from '@/lib/database'

const pool = await getSharedPgPool()
const { rows } = await pool.query(
  `SELECT id FROM entities WHERE ST_DWithin(location, ST_MakePoint($1, $2)::geography, $3)`,
  [lng, lat, radiusM]
)

typescript


await db().transaction(async (txn) => {
  const existing = await txn.read('usernames', usernameKey)
  if (existing) throw new Error('Username is taken')
  await txn.create('usernames', { userId, reservedAt: new Date() }, { id: usernameKey })
  await txn.update('users', userId, { username })
})

typescript


import { file } from '@/lib/file'

const result = await file().upload(`entities/${entityId}/logo.webp`, fileObject, {
  access: 'public',
  addRandomSuffix: false,
})
if (!result.success) throw new Error(result.error?.message ?? 'Upload failed')

SessionProvider

typescript


import { db } from '@/lib/database'

const result = await db().createDoc('entities', { name: 'Acme', type: 'technology' })
if (!result.success) throw result.error

const entity = await db().findDocById<Entity>('entities', id)
if (!entity.success) throw entity.error

const results = await db().queryDocs<Entity>({
  collection: 'entities',
  filters: [{ field: 'status', operator: '==', value: 'active' }],
  orderBy: [{ field: 'name', direction: 'asc' }],
  pagination: { limit: 20, offset: 0 },
})

typescript


import { getSharedPgPool } from '@/lib/database'

const pool = await getSharedPgPool()
const { rows } = await pool.query(
  `SELECT id FROM entities WHERE ST_DWithin(location, ST_MakePoint($1, $2)::geography, $3)`,
  [lng, lat, radiusM]
)

typescript


await db().transaction(async (txn) => {
  const existing = await txn.read('usernames', usernameKey)
  if (existing) throw new Error('Username is taken')
  await txn.create('usernames', { userId, reservedAt: new Date() }, { id: usernameKey })
  await txn.update('users', userId, { username })
})

typescript


import { file } from '@/lib/file'

const result = await file().upload(`entities/${entityId}/logo.webp`, fileObject, {
  access: 'public',
  addRandomSuffix: false,
})
if (!result.success) throw new Error(result.error?.message ?? 'Upload failed')

SessionProvider

typescript


import { db } from '@/lib/database'

const result = await db().createDoc('entities', { name: 'Acme', type: 'technology' })
if (!result.success) throw result.error

const entity = await db().findDocById<Entity>('entities', id)
if (!entity.success) throw entity.error

const results = await db().queryDocs<Entity>({
  collection: 'entities',
  filters: [{ field: 'status', operator: '==', value: 'active' }],
  orderBy: [{ field: 'name', direction: 'asc' }],
  pagination: { limit: 20, offset: 0 },
})

typescript


import { getSharedPgPool } from '@/lib/database'

const pool = await getSharedPgPool()
const { rows } = await pool.query(
  `SELECT id FROM entities WHERE ST_DWithin(location, ST_MakePoint($1, $2)::geography, $3)`,
  [lng, lat, radiusM]
)

typescript


await db().transaction(async (txn) => {
  const existing = await txn.read('usernames', usernameKey)
  if (existing) throw new Error('Username is taken')
  await txn.create('usernames', { userId, reservedAt: new Date() }, { id: usernameKey })
  await txn.update('users', userId, { username })
})

typescript


import { file } from '@/lib/file'

const result = await file().upload(`entities/${entityId}/logo.webp`, fileObject, {
  access: 'public',
  addRandomSuffix: false,
})
if (!result.success) throw new Error(result.error?.message ?? 'Upload failed')

Documentation

Quick entry (CTOs · auditors · agents)

Documentation

Quick entry (CTOs · auditors · agents)

Documentation

Quick entry (CTOs · auditors · agents)

Завантаження документації...

Documentation

Quick entry (CTOs · auditors · agents)

Завантаження документації...

Documentation

Quick entry (CTOs · auditors · agents)

Завантаження документації...

Documentation

Quick entry (CTOs · auditors · agents)

Завантаження документації...

Завантаження документації...

Завантаження документації...

Best Practices

Development principles

Quality over quantity

Security by convention

i18n is not optional

Respect the backend mode

Related documentation

Code structure

Performance

Backend modes

Data validation

Best Practices

Development principles

Quality over quantity

Security by convention

i18n is not optional

Respect the backend mode

Related documentation

Code structure

Performance

Backend modes

Data validation

Best Practices

Development principles

Quality over quantity

Security by convention

i18n is not optional

Respect the backend mode

Related documentation

Code structure

Performance

Backend modes

Data validation