Documentation

    Documentation

    Documentation

    Ring Platform Logo

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

    Підготовка контенту платформи Ring

    Ring Platform Logo

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

    Підготовка контенту платформи Ring

    Ring Platform Logo

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

    Підготовка контенту платформи Ring

    1. /
    2. /Code Structure

    Updated Jul 7, 20264 min listen

    1. /
    2. /Code Structure

    Updated Jul 7, 20264 min listen

    1. /
    2. /Code Structure

    Updated Jul 7, 20264 min listen

    Concepts, value, and typical clone scenarios — less code.

    Welcome to Ring
    Quick Reference
    Getting Started
    Prerequisites
    Installation
    First Success Validation
    Next Steps
    Architecture
    Data Model
    Real Time
    Discovery Mutation Sync
    Security
    Backend Services
    k8s-postgres-fcm Mode
    Firebase Integration
    Features
    Authentication
    Email AI-CRM
    Entities
    Opportunities
    Notifications
    Push Notifications with FCM (Ring-Powered)
    Tunnel Protocol
    Wallet & Credit System
    Multi-Vendor Store
    Referral Codes (Refcodes)
    Affiliate & Referral Enablement
    Payments Overview
    PaymentConductor
    SubscriptionConductor
    VideoConductor
    News Module - Digital Newspaper Experience
    Member Blogs
    Public Profile Pages
    Username Reservation System
    Scientific Editor
    Locale System
    Security & Compliance
    NFT Marketplace
    Token Staking System
    Performance Optimization Patterns
    Mobile Experience
    Wallet
    Wallet Security Tips
    API
    Authentication
    Email AI-CRM API
    Entities
    Opportunities
    Messaging API
    Notifications API
    Wallet API
    Store API
    Admin API
    Customization
    Quick Start — Your First Ring Clone
    Customization Guide
    Token Economics Setup
    Payment Gateway Integration
    Reference Ring deployments
    Branding
    Themes
    Web3
    Token launch jurisdictions
    Deployment
    Self-hosted deployment
    Vercel
    Docker
    Monitoring & Analytics
    Performance Optimization
    Backup & Recovery
    Development
    Local Setup
    Code Structure
    Documentation components
    Community tooling
    Ring MCP Server
    Generative Images (ImageConductor)
    Autonomous Newsroom (Grok)
    OSS vs enterprise
    Whitelabel Navigation
    Best Practices
    Workflow
    Code Style
    Performance
    Testing
    Deployment
    Debugging
    Contributing
    MCP
    ring-image-create
    ring-video-create
    Examples
    Quick Start
    White Label
    Real World
    Integrations
    Ethereum wallets (Wagmi v3)

    Quick entry (CTOs · auditors · agents)

    Welcome — mission & audiences
    Quick Reference
    Getting started
    Architecture & Auth.js
    Backend modes & databases (DB_BACKEND_MODE)
    Self-hosted
    Ring MCP Tools
    Ring MCP Server
    Token economics
    Token launch jurisdictions
    Deploy (Docker · k8s)
    Security & compliance reads
    ringdom.org — LegioX homebase
    Source — MIT license (GitHub)

    Concepts, value, and typical clone scenarios — less code.

    Welcome to Ring
    Quick Reference
    Getting Started
    Prerequisites
    Installation
    First Success Validation
    Next Steps
    Architecture
    Data Model
    Real Time
    Discovery Mutation Sync
    Security
    Backend Services
    k8s-postgres-fcm Mode
    Firebase Integration
    Features
    Authentication
    Email AI-CRM
    Entities
    Opportunities
    Notifications
    Push Notifications with FCM (Ring-Powered)
    Tunnel Protocol
    Wallet & Credit System
    Multi-Vendor Store
    Referral Codes (Refcodes)
    Affiliate & Referral Enablement
    Payments Overview
    PaymentConductor
    SubscriptionConductor
    VideoConductor
    News Module - Digital Newspaper Experience
    Member Blogs
    Public Profile Pages
    Username Reservation System
    Scientific Editor
    Locale System
    Security & Compliance
    NFT Marketplace
    Token Staking System
    Performance Optimization Patterns
    Mobile Experience
    Wallet
    Wallet Security Tips
    API
    Authentication
    Email AI-CRM API
    Entities
    Opportunities
    Messaging API
    Notifications API
    Wallet API
    Store API
    Admin API
    Customization
    Quick Start — Your First Ring Clone
    Customization Guide
    Token Economics Setup
    Payment Gateway Integration
    Reference Ring deployments
    Branding
    Themes
    Web3
    Token launch jurisdictions
    Deployment
    Self-hosted deployment
    Vercel
    Docker
    Monitoring & Analytics
    Performance Optimization
    Backup & Recovery
    Development
    Local Setup
    Code Structure
    Documentation components
    Community tooling
    Ring MCP Server
    Generative Images (ImageConductor)
    Autonomous Newsroom (Grok)
    OSS vs enterprise
    Whitelabel Navigation
    Best Practices
    Workflow
    Code Style
    Performance
    Testing
    Deployment
    Debugging
    Contributing
    MCP
    ring-image-create
    ring-video-create
    Examples
    Quick Start
    White Label
    Real World
    Integrations
    Ethereum wallets (Wagmi v3)

    Quick entry (CTOs · auditors · agents)

    Welcome — mission & audiences
    Quick Reference
    Getting started
    Architecture & Auth.js
    Backend modes & databases (DB_BACKEND_MODE)
    Self-hosted
    Ring MCP Tools
    Ring MCP Server
    Token economics
    Token launch jurisdictions
    Deploy (Docker · k8s)
    Security & compliance reads
    ringdom.org — LegioX homebase
    Source — MIT license (GitHub)

    Concepts, value, and typical clone scenarios — less code.

    Welcome to Ring
    Quick Reference
    Getting Started
    Prerequisites
    Installation
    First Success Validation
    Next Steps
    Architecture
    Data Model
    Real Time
    Discovery Mutation Sync
    Security
    Backend Services
    k8s-postgres-fcm Mode
    Firebase Integration
    Features
    Authentication
    Email AI-CRM
    Entities
    Opportunities
    Notifications
    Push Notifications with FCM (Ring-Powered)
    Tunnel Protocol
    Wallet & Credit System
    Multi-Vendor Store
    Referral Codes (Refcodes)
    Affiliate & Referral Enablement
    Payments Overview
    PaymentConductor
    SubscriptionConductor
    VideoConductor
    News Module - Digital Newspaper Experience
    Member Blogs
    Public Profile Pages
    Username Reservation System
    Scientific Editor
    Locale System
    Security & Compliance
    NFT Marketplace
    Token Staking System
    Performance Optimization Patterns
    Mobile Experience
    Wallet
    Wallet Security Tips
    API
    Authentication
    Email AI-CRM API
    Entities
    Opportunities
    Messaging API
    Notifications API
    Wallet API
    Store API
    Admin API
    Customization
    Quick Start — Your First Ring Clone
    Customization Guide
    Token Economics Setup
    Payment Gateway Integration
    Reference Ring deployments
    Branding
    Themes
    Web3
    Token launch jurisdictions
    Deployment
    Self-hosted deployment
    Vercel
    Docker
    Monitoring & Analytics
    Performance Optimization
    Backup & Recovery
    Development
    Local Setup
    Code Structure
    Documentation components
    Community tooling
    Ring MCP Server
    Generative Images (ImageConductor)
    Autonomous Newsroom (Grok)
    OSS vs enterprise
    Whitelabel Navigation
    Best Practices
    Workflow
    Code Style
    Performance
    Testing
    Deployment
    Debugging
    Contributing
    MCP
    ring-image-create
    ring-video-create
    Examples
    Quick Start
    White Label
    Real World
    Integrations
    Ethereum wallets (Wagmi v3)

    Quick entry (CTOs · auditors · agents)

    Welcome — mission & audiences
    Quick Reference
    Getting started
    Architecture & Auth.js
    Backend modes & databases (DB_BACKEND_MODE)
    Self-hosted
    Ring MCP Tools
    Ring MCP Server
    Token economics
    Token launch jurisdictions
    Deploy (Docker · k8s)
    Security & compliance reads
    ringdom.org — LegioX homebase
    Source — MIT license (GitHub)
    Docs
    Development
    Docs
    Development
    Docs
    Development

    Code Structure

    Ring Platform v1.6.4 organizes code by App Router route groups, feature domains, and a provider-owned hook layer that prevents duplicate network subscriptions.

    Use Founder / Developer tabs in the docs sidebar to filter this page. Shared sections below apply to both audiences; audience-specific blocks follow.

    Repository layout

    text
    
    ring-platform.org/
    ├── app/                    # Next.js 16 App Router + app/api route handlers
    ├── components/             # Shared UI, navigation, providers
    ├── features/               # Domain modules (auth, store, wallet, news, …)
    ├── hooks/                  # Root hooks — see hooks/HOOKS-README.md
    ├── lib/                    # database, payments, locale-config, tunnel
    ├── services/               # email AI CRM, blockchain oracle
    ├── locales/                # next-intl JSON bundles (en, uk, ru)
    ├── data/                   # schema.sql + migrations/
    └── docs/                   # MDX documentation (docs/{locale}/**)

    Not in public OSS tree: k8s/, cli/, propagation/ (gitignored).

    AreaPath
    PaymentConductorlib/payments/conductor/
    Locale SSOTlib/locale-config.ts, i18n/routing.ts
    Database abstractionlib/database/ (db(), getSharedPgPool())
    Auth.js v5auth.ts, features/auth/components/session-provider.tsx
    Client app shellcomponents/providers/app-client-shell.tsx

    Why structure matters for your clone

    A Ring clone is a white-label fork of this tree. Feature code stays inside features/{domain}/ so Reggie propagation and your customizations do not collide with core platform plumbing.

    Best practices

    Database, auth, and SSOT guardrails for clone operators hiring integrators.

    Performance patterns

    What keeps pages fast without extra infrastructure.

    Backend modes

    PostgreSQL-primary vs Firebase-backed deployments.

    Typical clone scenarios:

    • Commerce ring — extend , keep in the app shell.

    App Router

    Route groups isolate layouts and auth boundaries. Server Actions live in app/_actions/ (not @actions/).

    Features module pattern

    Cross-feature imports should go through each feature's index.ts export surface, not deep paths.

    Hooks and providers

    Root hooks live in hooks/. Provider-owned subscriptions prevent duplicate tunnel connections and API polls. Full reference: hooks/HOOKS-README.md (Provider matrix + P4 — duplicate-fetch consolidation, 2026-07-07).

    SSOT rule

    If a hook opens a tunnel channel or polls an API globally (unread count, credit balance, FCM token), mount it once in a provider. UI components consume context — they do not call the raw hook.

    Provider layers in app-client-shell.tsx

    Provider matrix (verified)

    Hook / concernOwnerContext / accessorNotes

    Related documentation

    Best practices

    db() rules, SSOT script gates, single-flight client caches.

    Hooks README

    In-repo SSOT: hooks/HOOKS-README.md.

    Realtime architecture

    TunnelHub, WSS routes, notification channel naming.

    Push notifications

    useFCM, Server Action registration, sign-out cleanup.

    Code Structure

    Ring Platform v1.6.4 organizes code by App Router route groups, feature domains, and a provider-owned hook layer that prevents duplicate network subscriptions.

    Use Founder / Developer tabs in the docs sidebar to filter this page. Shared sections below apply to both audiences; audience-specific blocks follow.

    Repository layout

    text
    
    ring-platform.org/
    ├── app/                    # Next.js 16 App Router + app/api route handlers
    ├── components/             # Shared UI, navigation, providers
    ├── features/               # Domain modules (auth, store, wallet, news, …)
    ├── hooks/                  # Root hooks — see hooks/HOOKS-README.md
    ├── lib/                    # database, payments, locale-config, tunnel
    ├── services/               # email AI CRM, blockchain oracle
    ├── locales/                # next-intl JSON bundles (en, uk, ru)
    ├── data/                   # schema.sql + migrations/
    └── docs/                   # MDX documentation (docs/{locale}/**)

    Not in public OSS tree: k8s/, cli/, propagation/ (gitignored).

    AreaPath
    PaymentConductorlib/payments/conductor/
    Locale SSOTlib/locale-config.ts, i18n/routing.ts
    Database abstractionlib/database/ (db(), getSharedPgPool())
    Auth.js v5auth.ts, features/auth/components/session-provider.tsx
    Client app shellcomponents/providers/app-client-shell.tsx

    Why structure matters for your clone

    A Ring clone is a white-label fork of this tree. Feature code stays inside features/{domain}/ so Reggie propagation and your customizations do not collide with core platform plumbing.

    Best practices

    Database, auth, and SSOT guardrails for clone operators hiring integrators.

    Performance patterns

    What keeps pages fast without extra infrastructure.

    Backend modes

    PostgreSQL-primary vs Firebase-backed deployments.

    Typical clone scenarios:

    • Commerce ring — extend , keep in the app shell.

    App Router

    Route groups isolate layouts and auth boundaries. Server Actions live in app/_actions/ (not @actions/).

    Features module pattern

    Cross-feature imports should go through each feature's index.ts export surface, not deep paths.

    Hooks and providers

    Root hooks live in hooks/. Provider-owned subscriptions prevent duplicate tunnel connections and API polls. Full reference: hooks/HOOKS-README.md (Provider matrix + P4 — duplicate-fetch consolidation, 2026-07-07).

    SSOT rule

    If a hook opens a tunnel channel or polls an API globally (unread count, credit balance, FCM token), mount it once in a provider. UI components consume context — they do not call the raw hook.

    Provider layers in app-client-shell.tsx

    Provider matrix (verified)

    Hook / concernOwnerContext / accessorNotes

    Related documentation

    Best practices

    db() rules, SSOT script gates, single-flight client caches.

    Hooks README

    In-repo SSOT: hooks/HOOKS-README.md.

    Realtime architecture

    TunnelHub, WSS routes, notification channel naming.

    Push notifications

    useFCM, Server Action registration, sign-out cleanup.

    Code Structure

    Ring Platform v1.6.4 organizes code by App Router route groups, feature domains, and a provider-owned hook layer that prevents duplicate network subscriptions.

    Use Founder / Developer tabs in the docs sidebar to filter this page. Shared sections below apply to both audiences; audience-specific blocks follow.

    Repository layout

    text
    
    ring-platform.org/
    ├── app/                    # Next.js 16 App Router + app/api route handlers
    ├── components/             # Shared UI, navigation, providers
    ├── features/               # Domain modules (auth, store, wallet, news, …)
    ├── hooks/                  # Root hooks — see hooks/HOOKS-README.md
    ├── lib/                    # database, payments, locale-config, tunnel
    ├── services/               # email AI CRM, blockchain oracle
    ├── locales/                # next-intl JSON bundles (en, uk, ru)
    ├── data/                   # schema.sql + migrations/
    └── docs/                   # MDX documentation (docs/{locale}/**)

    Not in public OSS tree: k8s/, cli/, propagation/ (gitignored).

    AreaPath
    PaymentConductorlib/payments/conductor/
    Locale SSOTlib/locale-config.ts, i18n/routing.ts
    Database abstractionlib/database/ (db(), getSharedPgPool())
    Auth.js v5auth.ts, features/auth/components/session-provider.tsx
    Client app shellcomponents/providers/app-client-shell.tsx

    Why structure matters for your clone

    A Ring clone is a white-label fork of this tree. Feature code stays inside features/{domain}/ so Reggie propagation and your customizations do not collide with core platform plumbing.

    Best practices

    Database, auth, and SSOT guardrails for clone operators hiring integrators.

    Performance patterns

    What keeps pages fast without extra infrastructure.

    Backend modes

    PostgreSQL-primary vs Firebase-backed deployments.

    Typical clone scenarios:

    • Commerce ring — extend , keep in the app shell.

    App Router

    Route groups isolate layouts and auth boundaries. Server Actions live in app/_actions/ (not @actions/).

    Features module pattern

    Cross-feature imports should go through each feature's index.ts export surface, not deep paths.

    Hooks and providers

    Root hooks live in hooks/. Provider-owned subscriptions prevent duplicate tunnel connections and API polls. Full reference: hooks/HOOKS-README.md (Provider matrix + P4 — duplicate-fetch consolidation, 2026-07-07).

    SSOT rule

    If a hook opens a tunnel channel or polls an API globally (unread count, credit balance, FCM token), mount it once in a provider. UI components consume context — they do not call the raw hook.

    Provider layers in app-client-shell.tsx

    Provider matrix (verified)

    Hook / concernOwnerContext / accessorNotes

    Related documentation

    Best practices

    db() rules, SSOT script gates, single-flight client caches.

    Hooks README

    In-repo SSOT: hooks/HOOKS-README.md.

    Realtime architecture

    TunnelHub, WSS routes, notification channel naming.

    Push notifications

    useFCM, Server Action registration, sign-out cleanup.

    features/store/
    StoreProvider
  1. Community ring — entities + opportunities under features/, tunnel providers unchanged.
  2. News/media ring — features/news/ services; do not duplicate global notification providers.
  3. use-auth.ts
    SessionProvider
    useAuth()
    SSOT: features/auth/components/session-provider.tsx — not components/providers/session-provider.tsx (deleted)
    use-fcm.tsFCMProviderinternal / useFCM() in provider onlyToken upsert via app/_actions/fcm.ts
    use-tunnel.tsTunnelProvideruseTunnel()Shared WSS/SSE connection
    use-unread-count.tsNotificationProvideruseNotificationContext()Nav badges must use context
    use-credit-balance.tsCreditBalanceProvideruseCreditBalanceContext()Module-scope bootstrap single-flight (5s TTL, keyed by userId)
    use-credit-history.tsCreditHistoryProvideruseCreditHistoryContext()Wallet routes only
    use-vendor-status.ts(no provider)useVendorStatus()Single-flight + 30s TTL; SSOT for GET /api/vendor/status
    Web VitalsWebVitalsProvider—Buffers metrics → one debounced POST /api/analytics/web-vitals

    SessionProvider tuning

    One 15-minute background poll; no refetch on focus/reconnect — cuts redundant GET /api/auth/session across every useSession() consumer.

    P4 duplicate-fetch fixes (2026-07-07)

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

    • Vendor status — hooks/use-vendor-status.ts replaces inline fetch('/api/vendor/status') in sidebar layouts.
    • Credit balance bootstrap — module-scope cache in hooks/use-credit-balance.ts survives Strict Mode remounts.
    • Web Vitals — components/providers/web-vitals-provider.tsx batches useReportWebVitals (1.5s debounce).
    • Store catalog — features/store/config.ts → getCachedProductCatalog() ('use cache' + cacheTag('store:products')).
    • SessionProvider — merged tuned settings; deleted duplicates components/providers/session-provider.tsx and auth-provider.tsx.

    Enforce locally:

    Lib directory essentials

    ModulePathRole
    Databaselib/database/db(), getSharedPgPool(), adapters
    Auth configauth.tsAuth.js v5 handlers + auth()
    Paymentslib/payments/conductor/PaymentConductor
    Localelib/locale-config.tsSSOT for en / uk / ru

    Use db() from @/lib/database for all domain persistence. getSharedPgPool() is the sanctioned escape hatch for PostGIS raw SQL only — never new Pool( outside lib/database/.

    Server Actions

    All Server Actions use file-level 'use server' in app/_actions/. Derive userId from await auth() — never from client parameters. See Best practices for the canonical pattern.

    text
    
    app/
    ├── (public)/[locale]/         # Marketing, store, blog
    ├── (authenticated)/[locale]/    # Editor, entities, settings
    ├── (admin)/[locale]/            # Admin panels
    ├── (confidential)/[locale]/     # Tier-gated docs
    ├── api/                         # Route handlers (auth, store, payments, …)
    ├── _actions/                    # Server Actions
    └── layout.tsx
    text
    
    features/{domain}/
    ├── components/
    ├── hooks/          # optional — domain-scoped only
    ├── services/
    ├── lib/
    └── index.ts        # public API
    features/store/
    StoreProvider
  4. Community ring — entities + opportunities under features/, tunnel providers unchanged.
  5. News/media ring — features/news/ services; do not duplicate global notification providers.
  6. use-auth.ts
    SessionProvider
    useAuth()
    SSOT: features/auth/components/session-provider.tsx — not components/providers/session-provider.tsx (deleted)
    use-fcm.tsFCMProviderinternal / useFCM() in provider onlyToken upsert via app/_actions/fcm.ts
    use-tunnel.tsTunnelProvideruseTunnel()Shared WSS/SSE connection
    use-unread-count.tsNotificationProvideruseNotificationContext()Nav badges must use context
    use-credit-balance.tsCreditBalanceProvideruseCreditBalanceContext()Module-scope bootstrap single-flight (5s TTL, keyed by userId)
    use-credit-history.tsCreditHistoryProvideruseCreditHistoryContext()Wallet routes only
    use-vendor-status.ts(no provider)useVendorStatus()Single-flight + 30s TTL; SSOT for GET /api/vendor/status
    Web VitalsWebVitalsProvider—Buffers metrics → one debounced POST /api/analytics/web-vitals

    SessionProvider tuning

    One 15-minute background poll; no refetch on focus/reconnect — cuts redundant GET /api/auth/session across every useSession() consumer.

    P4 duplicate-fetch fixes (2026-07-07)

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

    • Vendor status — hooks/use-vendor-status.ts replaces inline fetch('/api/vendor/status') in sidebar layouts.
    • Credit balance bootstrap — module-scope cache in hooks/use-credit-balance.ts survives Strict Mode remounts.
    • Web Vitals — components/providers/web-vitals-provider.tsx batches useReportWebVitals (1.5s debounce).
    • Store catalog — features/store/config.ts → getCachedProductCatalog() ('use cache' + cacheTag('store:products')).
    • SessionProvider — merged tuned settings; deleted duplicates components/providers/session-provider.tsx and auth-provider.tsx.

    Enforce locally:

    Lib directory essentials

    ModulePathRole
    Databaselib/database/db(), getSharedPgPool(), adapters
    Auth configauth.tsAuth.js v5 handlers + auth()
    Paymentslib/payments/conductor/PaymentConductor
    Localelib/locale-config.tsSSOT for en / uk / ru

    Use db() from @/lib/database for all domain persistence. getSharedPgPool() is the sanctioned escape hatch for PostGIS raw SQL only — never new Pool( outside lib/database/.

    Server Actions

    All Server Actions use file-level 'use server' in app/_actions/. Derive userId from await auth() — never from client parameters. See Best practices for the canonical pattern.

    text
    
    app/
    ├── (public)/[locale]/         # Marketing, store, blog
    ├── (authenticated)/[locale]/    # Editor, entities, settings
    ├── (admin)/[locale]/            # Admin panels
    ├── (confidential)/[locale]/     # Tier-gated docs
    ├── api/                         # Route handlers (auth, store, payments, …)
    ├── _actions/                    # Server Actions
    └── layout.tsx
    text
    
    features/{domain}/
    ├── components/
    ├── hooks/          # optional — domain-scoped only
    ├── services/
    ├── lib/
    └── index.ts        # public API
    features/store/
    StoreProvider
  7. Community ring — entities + opportunities under features/, tunnel providers unchanged.
  8. News/media ring — features/news/ services; do not duplicate global notification providers.
  9. use-auth.ts
    SessionProvider
    useAuth()
    SSOT: features/auth/components/session-provider.tsx — not components/providers/session-provider.tsx (deleted)
    use-fcm.tsFCMProviderinternal / useFCM() in provider onlyToken upsert via app/_actions/fcm.ts
    use-tunnel.tsTunnelProvideruseTunnel()Shared WSS/SSE connection
    use-unread-count.tsNotificationProvideruseNotificationContext()Nav badges must use context
    use-credit-balance.tsCreditBalanceProvideruseCreditBalanceContext()Module-scope bootstrap single-flight (5s TTL, keyed by userId)
    use-credit-history.tsCreditHistoryProvideruseCreditHistoryContext()Wallet routes only
    use-vendor-status.ts(no provider)useVendorStatus()Single-flight + 30s TTL; SSOT for GET /api/vendor/status
    Web VitalsWebVitalsProvider—Buffers metrics → one debounced POST /api/analytics/web-vitals

    SessionProvider tuning

    One 15-minute background poll; no refetch on focus/reconnect — cuts redundant GET /api/auth/session across every useSession() consumer.

    P4 duplicate-fetch fixes (2026-07-07)

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

    • Vendor status — hooks/use-vendor-status.ts replaces inline fetch('/api/vendor/status') in sidebar layouts.
    • Credit balance bootstrap — module-scope cache in hooks/use-credit-balance.ts survives Strict Mode remounts.
    • Web Vitals — components/providers/web-vitals-provider.tsx batches useReportWebVitals (1.5s debounce).
    • Store catalog — features/store/config.ts → getCachedProductCatalog() ('use cache' + cacheTag('store:products')).
    • SessionProvider — merged tuned settings; deleted duplicates components/providers/session-provider.tsx and auth-provider.tsx.

    Enforce locally:

    Lib directory essentials

    ModulePathRole
    Databaselib/database/db(), getSharedPgPool(), adapters
    Auth configauth.tsAuth.js v5 handlers + auth()
    Paymentslib/payments/conductor/PaymentConductor
    Localelib/locale-config.tsSSOT for en / uk / ru

    Use db() from @/lib/database for all domain persistence. getSharedPgPool() is the sanctioned escape hatch for PostGIS raw SQL only — never new Pool( outside lib/database/.

    Server Actions

    All Server Actions use file-level 'use server' in app/_actions/. Derive userId from await auth() — never from client parameters. See Best practices for the canonical pattern.

    text
    
    app/
    ├── (public)/[locale]/         # Marketing, store, blog
    ├── (authenticated)/[locale]/    # Editor, entities, settings
    ├── (admin)/[locale]/            # Admin panels
    ├── (confidential)/[locale]/     # Tier-gated docs
    ├── api/                         # Route handlers (auth, store, payments, …)
    ├── _actions/                    # Server Actions
    └── layout.tsx
    text
    
    features/{domain}/
    ├── components/
    ├── hooks/          # optional — domain-scoped only
    ├── services/
    ├── lib/
    └── index.ts        # public API
    typescript
    
    // features/auth/components/session-provider.tsx
    <NextAuthSessionProvider
      session={session}
      refetchInterval={15 * 60}
      refetchOnWindowFocus={false}
      refetchWhenOffline={false}
    >
    bash
    
    ./scripts/validate-provider-ssot.sh
    typescript
    
    // features/auth/components/session-provider.tsx
    <NextAuthSessionProvider
      session={session}
      refetchInterval={15 * 60}
      refetchOnWindowFocus={false}
      refetchWhenOffline={false}
    >
    bash
    
    ./scripts/validate-provider-ssot.sh
    typescript
    
    // features/auth/components/session-provider.tsx
    <NextAuthSessionProvider
      session={session}
      refetchInterval={15 * 60}
      refetchOnWindowFocus={false}
      refetchWhenOffline={false}
    >
    bash
    
    ./scripts/validate-provider-ssot.sh