Loading documentation...
Preparing Ring content
Concepts, value, and typical clone scenarios — less code.
Concepts, value, and typical clone scenarios — less code.
Preparing Ring content
Preparing Ring content
Preparing Ring content
Use the Founder / Developer tabs to filter this page for your role. The DB_BACKEND_MODE environment variable is required — the platform will not start without it.
Ring Platform uses a single codebase with a required runtime switch: DB_BACKEND_MODE. The value selects which database adapters are registered, whether Firestore is used for application data, and how push notifications are wired.
| Mode | Primary database | Firebase use | Best for |
|---|---|---|---|
k8s-postgres-fcm | PostgreSQL 16 + PostGIS | FCM push only | Production self-hosted, local dev |
firebase-full | Firestore (first-class) | Everything: DB, FCM, Storage, AI, Hosting | Vercel Edge, clones, rapid prototyping |
supabase-fcm | Supabase PostgreSQL | FCM push only | Managed cloud PostgreSQL |
Naming: Production on your own Postgres is often described as "self‑hosted PostgreSQL + FCM." The enum value remains k8s-postgres-fcm — renaming would break every deployment and clone without a coordinated migration.
Implementation files: lib/database/backend-mode-config.ts, lib/database/DatabaseService.ts, lib/database/BackendSelector.ts, lib/database/shared-pg-pool.ts, lib/services/firebase-service-manager.ts (SSOT helpers for firebase-full).
| Scenario | Recommended mode | Why |
|---|---|---|
| Self-hosted production (k3s, K8s) | k8s-postgres-fcm | Full data sovereignty, PostgreSQL performance, PostGIS spatial queries |
| Rapid prototyping / MVP | firebase-full | Zero database provisioning, free FCM push, auto-scale |
| Ring clone (white-label) | firebase-full | No PostgreSQL dependency for the clone operator |
| Vercel Edge deployment | firebase-full | Vercel Edge Runtime + Firestore = no cold-start DB connection |
| Cloud PostgreSQL (no K8s) | supabase-fcm |
Use the Founder / Developer tabs to filter this page for your role. The DB_BACKEND_MODE environment variable is required — the platform will not start without it.
Ring Platform uses a single codebase with a required runtime switch: DB_BACKEND_MODE. The value selects which database adapters are registered, whether Firestore is used for application data, and how push notifications are wired.
| Mode | Primary database | Firebase use | Best for |
|---|---|---|---|
k8s-postgres-fcm | PostgreSQL 16 + PostGIS | FCM push only | Production self-hosted, local dev |
firebase-full | Firestore (first-class) | Everything: DB, FCM, Storage, AI, Hosting | Vercel Edge, clones, rapid prototyping |
supabase-fcm | Supabase PostgreSQL | FCM push only | Managed cloud PostgreSQL |
Naming: Production on your own Postgres is often described as "self‑hosted PostgreSQL + FCM." The enum value remains k8s-postgres-fcm — renaming would break every deployment and clone without a coordinated migration.
Implementation files: lib/database/backend-mode-config.ts, lib/database/DatabaseService.ts, lib/database/BackendSelector.ts, lib/database/shared-pg-pool.ts, lib/services/firebase-service-manager.ts (SSOT helpers for firebase-full).
| Scenario | Recommended mode | Why |
|---|---|---|
| Self-hosted production (k3s, K8s) | k8s-postgres-fcm | Full data sovereignty, PostgreSQL performance, PostGIS spatial queries |
| Rapid prototyping / MVP | firebase-full | Zero database provisioning, free FCM push, auto-scale |
| Ring clone (white-label) | firebase-full | No PostgreSQL dependency for the clone operator |
| Vercel Edge deployment | firebase-full | Vercel Edge Runtime + Firestore = no cold-start DB connection |
| Cloud PostgreSQL (no K8s) | supabase-fcm |
Use the Founder / Developer tabs to filter this page for your role. The DB_BACKEND_MODE environment variable is required — the platform will not start without it.
Ring Platform uses a single codebase with a required runtime switch: DB_BACKEND_MODE. The value selects which database adapters are registered, whether Firestore is used for application data, and how push notifications are wired.
| Mode | Primary database | Firebase use | Best for |
|---|---|---|---|
k8s-postgres-fcm | PostgreSQL 16 + PostGIS | FCM push only | Production self-hosted, local dev |
firebase-full | Firestore (first-class) | Everything: DB, FCM, Storage, AI, Hosting | Vercel Edge, clones, rapid prototyping |
supabase-fcm | Supabase PostgreSQL | FCM push only | Managed cloud PostgreSQL |
Naming: Production on your own Postgres is often described as "self‑hosted PostgreSQL + FCM." The enum value remains k8s-postgres-fcm — renaming would break every deployment and clone without a coordinated migration.
Implementation files: lib/database/backend-mode-config.ts, lib/database/DatabaseService.ts, lib/database/BackendSelector.ts, lib/database/shared-pg-pool.ts, lib/services/firebase-service-manager.ts (SSOT helpers for firebase-full).
| Scenario | Recommended mode | Why |
|---|---|---|
| Self-hosted production (k3s, K8s) | k8s-postgres-fcm | Full data sovereignty, PostgreSQL performance, PostGIS spatial queries |
| Rapid prototyping / MVP | firebase-full | Zero database provisioning, free FCM push, auto-scale |
| Ring clone (white-label) | firebase-full | No PostgreSQL dependency for the clone operator |
| Vercel Edge deployment | firebase-full | Vercel Edge Runtime + Firestore = no cold-start DB connection |
| Cloud PostgreSQL (no K8s) | supabase-fcm |
| Managed PostgreSQL with Supabase, FCM push |
| Push notifications needed | Any mode | FCM is optional and available in all three modes |
In k8s-postgres-fcm and supabase-fcm, every feature module shares one adapter pool. You do not get surprise connection spikes when admin settings, wallet oracle, geolocation, or email CRM load concurrently — they all route through db() or the sanctioned getSharedPgPool() escape hatch for PostGIS.
| Aspect | k8s-postgres-fcm | firebase-full | supabase-fcm |
|---|---|---|---|
| Database | Infrastructure cost only | Pay-per-read/write | Supabase tier pricing |
| Push (FCM) | Free | Free | Free |
| Storage | Vercel Blob / self-hosted | Firebase Storage (free tier) | Supabase Storage |
| Compute | K8s / Docker | Vercel Edge / Cloud Run | Vercel / Cloud Run |
| AI | LLM client via lib/ai/llm-client.ts | Firebase AI Logic + Gemini | LLM client via lib/ai/llm-client.ts |
db() / PostgreSQLAdaptergetAdminDb() returns a mock Firestore when shouldUseFirebaseForDatabase() is falsebuild-mock.server.ts provides type-compatible mocks during SSG and Postgres-primary modesFirebaseAdapterlib/services/firebase-service-manager.ts provides 30+ React 19 cache()-native SSOT helpersEliminates duplicate Firestore reads within a single SSG/SSR cycle.
DB_BACKEND_MODE=supabase-fcm — PostgreSQL on Supabase; same Postgres-primary + FCM pattern as k8s modeNEXT_PUBLIC_TUNNEL_TRANSPORT=supabase) — optional Realtime channel in lib/tunnel/transports/supabase-transport.ts. Orthogonal to which SQL backend owns your tables.Auth tables live in PostgreSQL (k8s-postgres-fcm, supabase-fcm) or Firestore (firebase-full). See lib/auth/postgres-adapter.ts / data/schema.sql for the SQL path.
// lib/database/backend-mode-config.ts
export type BackendMode = 'k8s-postgres-fcm' | 'firebase-full' | 'supabase-fcm'
export function shouldUseFirebaseForDatabase(): boolean {
return detectBackendMode() === 'firebase-full'
}
import { cache } from 'react'
export const getCachedUserCreditBalance = cache(async (userId: string) => {
// Firestore read — cached for the duration of the request
})| Managed PostgreSQL with Supabase, FCM push |
| Push notifications needed | Any mode | FCM is optional and available in all three modes |
In k8s-postgres-fcm and supabase-fcm, every feature module shares one adapter pool. You do not get surprise connection spikes when admin settings, wallet oracle, geolocation, or email CRM load concurrently — they all route through db() or the sanctioned getSharedPgPool() escape hatch for PostGIS.
| Aspect | k8s-postgres-fcm | firebase-full | supabase-fcm |
|---|---|---|---|
| Database | Infrastructure cost only | Pay-per-read/write | Supabase tier pricing |
| Push (FCM) | Free | Free | Free |
| Storage | Vercel Blob / self-hosted | Firebase Storage (free tier) | Supabase Storage |
| Compute | K8s / Docker | Vercel Edge / Cloud Run | Vercel / Cloud Run |
| AI | LLM client via lib/ai/llm-client.ts | Firebase AI Logic + Gemini | LLM client via lib/ai/llm-client.ts |
db() / PostgreSQLAdaptergetAdminDb() returns a mock Firestore when shouldUseFirebaseForDatabase() is falsebuild-mock.server.ts provides type-compatible mocks during SSG and Postgres-primary modesFirebaseAdapterlib/services/firebase-service-manager.ts provides 30+ React 19 cache()-native SSOT helpersEliminates duplicate Firestore reads within a single SSG/SSR cycle.
DB_BACKEND_MODE=supabase-fcm — PostgreSQL on Supabase; same Postgres-primary + FCM pattern as k8s modeNEXT_PUBLIC_TUNNEL_TRANSPORT=supabase) — optional Realtime channel in lib/tunnel/transports/supabase-transport.ts. Orthogonal to which SQL backend owns your tables.Auth tables live in PostgreSQL (k8s-postgres-fcm, supabase-fcm) or Firestore (firebase-full). See lib/auth/postgres-adapter.ts / data/schema.sql for the SQL path.
// lib/database/backend-mode-config.ts
export type BackendMode = 'k8s-postgres-fcm' | 'firebase-full' | 'supabase-fcm'
export function shouldUseFirebaseForDatabase(): boolean {
return detectBackendMode() === 'firebase-full'
}
import { cache } from 'react'
export const getCachedUserCreditBalance = cache(async (userId: string) => {
// Firestore read — cached for the duration of the request
})| Managed PostgreSQL with Supabase, FCM push |
| Push notifications needed | Any mode | FCM is optional and available in all three modes |
In k8s-postgres-fcm and supabase-fcm, every feature module shares one adapter pool. You do not get surprise connection spikes when admin settings, wallet oracle, geolocation, or email CRM load concurrently — they all route through db() or the sanctioned getSharedPgPool() escape hatch for PostGIS.
| Aspect | k8s-postgres-fcm | firebase-full | supabase-fcm |
|---|---|---|---|
| Database | Infrastructure cost only | Pay-per-read/write | Supabase tier pricing |
| Push (FCM) | Free | Free | Free |
| Storage | Vercel Blob / self-hosted | Firebase Storage (free tier) | Supabase Storage |
| Compute | K8s / Docker | Vercel Edge / Cloud Run | Vercel / Cloud Run |
| AI | LLM client via lib/ai/llm-client.ts | Firebase AI Logic + Gemini | LLM client via lib/ai/llm-client.ts |
db() / PostgreSQLAdaptergetAdminDb() returns a mock Firestore when shouldUseFirebaseForDatabase() is falsebuild-mock.server.ts provides type-compatible mocks during SSG and Postgres-primary modesFirebaseAdapterlib/services/firebase-service-manager.ts provides 30+ React 19 cache()-native SSOT helpersEliminates duplicate Firestore reads within a single SSG/SSR cycle.
DB_BACKEND_MODE=supabase-fcm — PostgreSQL on Supabase; same Postgres-primary + FCM pattern as k8s modeNEXT_PUBLIC_TUNNEL_TRANSPORT=supabase) — optional Realtime channel in lib/tunnel/transports/supabase-transport.ts. Orthogonal to which SQL backend owns your tables.Auth tables live in PostgreSQL (k8s-postgres-fcm, supabase-fcm) or Firestore (firebase-full). See lib/auth/postgres-adapter.ts / data/schema.sql for the SQL path.
// lib/database/backend-mode-config.ts
export type BackendMode = 'k8s-postgres-fcm' | 'firebase-full' | 'supabase-fcm'
export function shouldUseFirebaseForDatabase(): boolean {
return detectBackendMode() === 'firebase-full'
}
import { cache } from 'react'
export const getCachedUserCreditBalance = cache(async (userId: string) => {
// Firestore read — cached for the duration of the request
})