---
title: "Архітектура"
description: "Системна схема Ring Platform — Postgres-primary деплої, Auth.js, PaymentConductor, realtime та white-label (v1.6.0)"
locale: "uk"
---
# Архітектура

> **Info**
> **Для керівників:** Ring — **white-label платформа**: один код, багато брендованих деплоїв. Продакшен-кільця працюють на **PostgreSQL-primary** у Kubernetes, Firebase лише для **push**, платежі через **PaymentConductor**, локалізація без циклів редіректів авторизації.

Ring Platform v1.6.0 — **багатотенантний Next.js застосунок** з єдиним контрактом `DatabaseService`, конфігурованими платежами та опційним Web3/токенним шаром на клон. Ця сторінка — **хаб архітектури**; кожна тема має окрему глибоку статтю.

## Платформа одним поглядом

| Вимір | Підхід Ring |
|-------|-------------|
| **Застосунок** | Next.js 16 App Router, React 19 Server Components, Tailwind 4 |
| **Дані (продакшен)** | `DB_BACKEND_MODE=k8s-postgres-fcm` — Postgres + PostGIS, JSONB-first |
| **Автентифікація** | Auth.js v5 — `auth()` на рівні layout, тонкий `proxy.ts` лише для локалі |
| **Платежі** | PaymentConductor — WayForPay, Stripe, ledger + webhooks |
| **Realtime** | TunnelHub — native WSS / SSE / poll; `RING_DEPLOY_TARGET` |
| **Файли** | Vercel Blob або сховище клону |
| **Деплой** | k3s (кільця ringdom.org) — не Vercel Postgres |
| **Розширення** | White-label env, portal config, токен-контракти на клон |

## Системна карта

```mermaid
flowchart TB
  subgraph Client
    Web[Браузер / PWA]
    Admin[Адмін-консоль]
  end

  subgraph Edge["Next.js (proxy + RSC)"]
    Proxy[proxy.ts — лише локаль]
    Layouts[Route layouts — auth gates]
    SA[Server Actions + Route Handlers]
  end

  subgraph Core["Доменні сервіси"]
    DBsvc[DatabaseService / BackendSelector]
    Pay[PaymentConductor]
    Sub[Membership + credit ledger]
    RT[Tunnel transports]
    AI[AI matcher + Email CRM]
  end

  subgraph Data
    PG[(PostgreSQL)]
    FCM[Firebase FCM — лише push]
    Blob[Blob storage]
    Chain[Polygon — опційно Web3]
  end

  Web --> Proxy --> Layouts --> SA
  Admin --> Layouts
  SA --> DBsvc --> PG
  SA --> Pay
  SA --> Sub
  SA --> RT
  SA --> AI
  DBsvc -.-> FCM
  SA --> Blob
  Sub -.-> Chain
```

### Шлях запиту

```mermaid
sequenceDiagram
    participant B as Браузер
    participant P as proxy.ts
    participant L as authenticated layout
    participant A as auth()
    participant S as Server Action / API
    participant D as DatabaseService

    B->>P: GET /dashboard
    P->>P: Locale rewrite (next-intl)
    P->>L: Forward
    L->>A: Перевірка сесії
    alt немає сесії
      A-->>B: Redirect /login
    else ok
      L->>S: Mutation або loader
      S->>D: query / create / update
      D-->>B: RSC stream + client islands
    end
```

**Орієнтири в коді**

| Тема | Де читати |
|------|-----------|
| Locale proxy | `proxy.ts`, `lib/proxy-intl.ts` |
| Auth enforcement | `(authenticated)/[locale]/layout.tsx`, `auth.config.ts` |
| Режим БД | `lib/database/backend-mode-config.ts` |
| Платежі | `features/store/services/payment-conductor*` |
| Схема SSOT | `data/schema.sql` |

**Шари компонентів**

- **Hooks** — дані, кредит гаманця, realtime підписки
- **Feature components** — store, messages, wallet (повторне використання)
- **Pages** — композиція features; без прямих викликів адаптерів у UI

### Чеклист деплою

1. **`DB_BACKEND_MODE`** — `k8s-postgres-fcm` для self-hosted Postgres (канонічне ім’я enum).
2. **Postgres** + міграції (`getting-started/migrations`).
3. **FCM** — якщо потрібен push; Firebase **не** основна БД у Postgres-режимі.
4. **PaymentConductor** — WayForPay / Stripe, webhook URLs.
5. **Ingress** на Next.js; секрети в k8s.
6. Опційно: контракти **RING** / **ReferralRewards**; `NEXT_PUBLIC_RING_TOKEN_ADDRESS`.

### Чого ми *не* використовуємо

- `@vercel/postgres` як основний SQL драйвер
- Auth у `proxy.ts` (цикли редіректів — zero-loop proxy)
- Firestore як source of truth при `k8s-postgres-fcm`

### Сигнали моніторингу

- API p95, невдалі payment webhooks, помилки продовження підписок
- Насичення пулу з’єднань БД, drift версій міграцій
- Помилки FCM токенів, відключення Tunnel

## Глибокі розділи

  
- **[Режими бекенду та БД](/docs/architecture/backend-modes-and-databases.md)** — Матриця `DB_BACKEND_MODE` — Postgres vs Firebase vs Supabase, FCM-only Firebase

  
- **[Модель даних](/docs/architecture/data-model.md)** — JSONB-first схема, PostGIS, контракт collections, міграції

  
- **[Аутентифікація](/docs/architecture/authentication.md)** — Auth.js v5, JWT сесії, Postgres adapter, ролі

  
- **[Proxy та i18n](/docs/architecture/proxy-and-intl.md)** — Тонкий proxy, auth у layout, `localePrefix: as-needed`

  
- **[PaymentConductor](/docs/architecture/payment-conductor.md)** — Процесори, ledger `payment_transactions`, єдині webhooks

  
- **[Email AI-CRM](/docs/architecture/email-ai-crm.md)** — IMAP ingest, JSONB таблиці, cron poll, адмін-рев’ю

  
- **[News Kingdom](/docs/architecture/news-kingdom.md)** — Редакційний pipeline, generative newsroom, публікації

  
- **[Refcodes](/docs/architecture/refcodes.md)** — Реферальний граф, on-chain винагороди, idempotent minter

  
- **[Real-time](/docs/architecture/real-time.md)** — Tunnel transports, WebSocket/SSE, pooling

  
- **[Безпека](/docs/architecture/security.md)** — Defense in depth, секрети, верифікація webhooks, адмін-межі

## Сквозні потоки

### Комерція + членство

Checkout через **PaymentConductor** (fiat) або **RING credit / on-chain** підписку. Settlement і комісії — у [PaymentConductor](/docs/architecture/payment-conductor.md) та store guides.

### Контент + локаль

Публічні сторінки — **next-intl**. Документація та новини — файли `docs/{locale}/`. EN канонічний, якщо LOCALE-GAPS не позначає стислий UK/RU summary.

### White-label клони

Форк репо, portal branding, режим БД, опційна токеноміка — [White-label quick start](/docs/customization/quick-start.md), [Token economics](/docs/customization/token-economics.md).

> **Success**
> **Базис v1.6.0:** Postgres-primary + PaymentConductor + slim proxy + locale system. Почніть з [Режимів бекенду](/docs/architecture/backend-modes-and-databases.md), потім [Environment](/docs/deployment/environment.md).

> **Warning**
> **`DB_HYBRID_MODE` ≠ `DB_BACKEND_MODE`.** Для нових деплоїв використовуйте `DB_BACKEND_MODE`; legacy hybrid — на сторінці backend-modes.