microdao-daarion/docs/cursor/25_deployment_infrastructure.md

# 25 — Deployment & Infrastructure (MicroDAO)

*Deployment процес, середовища, інфраструктура, CI/CD, моніторинг*

---

## 1. Purpose & Scope

Цей документ описує інфраструктуру розгортання та процеси деплою для:

- microdao (messenger + agents + governance + wallet);
- DAARION.city core (Second Me, Gift Fabric, Citizenship);
- інтеграційних модулів (Embassy, RWA, Energy Union, GREENFOOD та ін.);
- Event-driven шару (NATS/JetStream / Outbox).

Ціль:

- чітко визначити середовища (local/dev/staging/prod);
- описати основні компоненти інфра-стеку;
- стандартизувати CI/CD pipeline та керування міграціями;
- визначити моніторинг, логування, backup/restore.

---

## 2. Environments

### 2.1 Local

Призначення:

- швидка розробка;
- інтеграційні тести окремого розробника.

Особливості:

- Postgres (може бути Supabase local або Docker);
- NATS/JetStream локально (Docker);
- фронтенд (Next.js / React) — `localhost:3000`;
- backend/edge functions — `localhost:PORT`;
- спрощена конфігурація OAuth/Email.

### 2.2 Dev

Призначення:

- інтеграція гілок;
- тестування нових фіч командою.

Особливості:

- часто автодеплой з `develop` / `dev` гілки;
- нестабільне середовище, допускається breaking changes;
- окремі ресурси БД, NATS, storage.

### 2.3 Staging

Призначення:

- передпродакшн середовище, максимально наближене до прод;
- тестування релізів перед викоткою на prod;
- smoke-тести, регресія, перевірка міграцій.

Особливості:

- конфігурації максимально збігаються з prod;
- ті ж версії Postgres/NATS/Redis;
- мінімум тестових даних, максимально наближені сценарії.

### 2.4 Prod

Призначення:

- бойове середовище для реальних користувачів та агентів;
- висока доступність, резервування, SLA.

Особливості:

- реплікація БД;
- резервні копії (snapshots + PITR);
- горизонтальне масштабування критичних сервісів;
- жорсткі політики безпеки, rate limiting, WAF.

---

## 3. Core Infrastructure Components

### 3.1 Database Layer

- **Postgres** (Supabase / керований Postgres):
  - основні таблиці: `users`, `teams`, `channels`, `messages`, `projects`, `tasks`, `agents`, `wallets`, `staking_ringk`, `payouts`, `rwa_inventory`, `embassy_*`, `access_keys`, `capabilities`, `bundles`, `audit_log`, `outbox_events`.
  - схема й міграції описані в `27_database_schema_migrations.md`.

Рекомендації:

- один кластер на середовище (dev/staging/prod);
- не змішувати dev/staging/prod в одному кластері;
- використовувати read-replicas для prod (аналітика, довгі запити).

### 3.2 Event Bus

- **NATS JetStream** (або інший стейтовий event bus):
  - теми (topics) з `Data Model & Event Catalog`;
  - консьюмери: Wallet service, Gift Fabric, Embassies, Telemetry.

Роль:

- децентралізований шар подій;
- відв'язка інтерфейсу, агентів і бекенду;
- реалізація Outbox pattern (`outbox_events` → NATS).

### 3.3 Application Layer

- **API Gateway / Edge Functions**:
  - REST/gRPC/API для frontend, агентів, інтеграцій;
  - PEP (Policy Enforcement Point) для capability-check;
  - валідація access keys, підписів Embassy, rate limiting.

- **Domain Services** (можуть бути edge functions / окремі сервіси):
  - Messaging Service (channels/messages/followups);
  - Projects/Tasks Service;
  - Agent Orchestrator (agent_runs, router);
  - Wallet & Payouts;
  - Embassy Service;
  - Governance Service.

### 3.4 Frontend

- SPA/SSR (React/Next.js):
  - DAARION.city UI;
  - microdao messenger + agents;
  - admin-консоль (telemetry, управління платформи).

Рекомендації:

- окремі build'и для user-facing (місто) і admin/ops;
- environment-specific base URLs.

### 3.5 Object Storage

- зберігання файлів/документів/зображень:
  - user uploads (файли в каналах, документи);
  - логи агентів (якщо великі);
  - snapshot-и моделей/конфігів (якщо потрібно).

---

## 4. High-level Topology

Текстовий опис (спрощено):

- Frontend (Web) → API Gateway
- API Gateway → Postgres / NATS / Services
- Agent Mesh ↔ API Gateway ↔ NATS
- Embassy Webhooks ↔ API Gateway ↔ NATS ↔ Services
- Observability Stack (Prometheus/Grafana/Logs) → читає метрики з усіх компонентів

(Опційно можна додати Mermaid-діаграму у цьому файлі.)

---

## 5. Deployment Workflows

### 5.1 Local

- `docker-compose` / Supabase local:
  - `postgres`, `nats`, `minio` (опційно), `api`, `web`.
- Команди:
  - `npm run dev` (web);
  - `supabase db push` / `pnpm prisma migrate` / `golang-migrate up` (залежно від стеку);
  - запуск background workers для Outbox → NATS.

### 5.2 Dev

Trigger:

- push в `develop` / `dev` гілку.

Кроки:

1. CI: `lint`, `tests`, `typecheck`.
2. Build:
   - web (static/SSR bundle);
   - backend/edge functions (docker image або окремі функції).
3. Deploy:
   - apply DB migrations;
   - деплой API/edge;
   - деплой web (dev URL).
4. Smoke-тести:
   - healthcheck endpoints;
   - простий сценарій (login → створити канал → відправити повідомлення).

### 5.3 Staging

Trigger:

- merge/push у `main` з тегом `rc-*` або окрема `release/*` гілка.

Кроки:

1. CI повторює dev-пайплайн.
2. DB migrations:
   - запуск у режимі dry-run (якщо підтримується);
   - застосування на staging.
3. Deploy API, workers, web (staging domain).
4. Інтеграційні тести:
   - агенти, Embassy вебхуки, payouts, RWA, governance flows.

### 5.4 Prod

Trigger:

- тег `vX.Y.Z` або manual approval релізу.

Кроки:

1. Freeze staging (ті самі артефакти).
2. Backup prod DB (snapshot).
3. Apply migrations на prod.
4. Deploy API/edge з поетапним rollout (canary / по одному інстансу).
5. Deploy web (атомарна заміна, rollback через попередній build).
6. Post-deploy чек-лист:
   - логін/чат;
   - ворк агента;
   - простий payout симуляційний (якщо є test mode);
   - кілька Embassy викликів у test-конфігурації.

---

## 6. Configuration & Environment Variables

Приклад розділів `.env` (загальні ключі):

### 6.1 Database

- `DB_HOST`
- `DB_PORT`
- `DB_NAME`
- `DB_USER`
- `DB_PASSWORD`
- `DB_SSLMODE` (prod: `require`)

### 6.2 NATS / Event Bus

- `NATS_URL`
- `NATS_USER`
- `NATS_PASSWORD`
- `NATS_STREAM_EVENTS` (ім'я стріму для event catalog)
- `NATS_CONSUMER_WALLET`
- `NATS_CONSUMER_EMBASSY`
- `NATS_CONSUMER_GIFT_FABRIC`

### 6.3 Auth / Security

- `JWT_SECRET` (для capability-token, якщо локально)
- `SESSION_SECRET`
- `E2EE_PUBLIC_KEY` / `E2EE_PRIVATE_KEY` (або інший механізм)
- `RATE_LIMIT_GLOBAL`
- `RATE_LIMIT_PER_KEY`

### 6.4 Embassy

- `EMBASSY_WEBHOOK_SECRET_ENERGY_UNION`
- `EMBASSY_WEBHOOK_SECRET_GREENFOOD`
- `EMBASSY_WEBHOOK_SECRET_WATER_UNION`
- `EMBASSY_WEBHOOK_SECRET_ESSENCE_STREAM`

### 6.5 Wallet / Chain

- `CHAIN_RPC_URL`
- `CHAIN_EXPLORER_URL`
- `WALLET_SAFE_ADDRESS` (якщо multi-sig)
- `WALLET_PRIVATE_KEY` (краще в KMS, не у .env)

---

## 7. Secrets Management

- Prod/staging secrets **не зберігати** у `.env` у репозиторії.
- Використовувати:
  - KMS (GCP/AWS/Azure) або
  - менеджер секретів (Vault, Doppler, SSM Parameter Store тощо).
- Workers/API при старті:
  - тягнуть секрети з KMS/secret manager;
  - кешують лише в пам'яті (не логувати).

Особливо чутливі:

- ключі Embassy Webhooks;
- wallet private keys / hot signer;
- JWT/Session secrets.

---

## 8. Database Migrations

Посилання: `27_database_schema_migrations.md`.

Правила:

1. Міграції **ніколи** не змінюють/ламають дані під час prod розгортання без попередніх data-migrations.
2. `up`/`down` повинні бути ідемпотентними (DROP IF EXISTS / CREATE IF NOT EXISTS).
3. Порядок виконання:
   - local: розробник запускає всі `000XXX_*.sql` + `seeds.sql`;
   - dev/staging/prod: CI/CD застосовує міграції у правильному порядку.

---

## 9. Event Bus & Outbox Pattern

- Event producer-и (API/Services) не відправляють події напряму в NATS у критичних шляхах — спочатку пишуть у `outbox_events`.
- Background worker:
  - читає `outbox_events` з `processed=false`;
  - публікує у NATS відповідний topic;
  - позначає `processed=true`, `processed_at=NOW()`.

Це зменшує ймовірність втрати подій при часткових збоях.

---

## 10. Monitoring & Logging

### 10.1 Метрики

- **API/Backend**:
  - latency per endpoint;
  - error rate (5xx, 4xx);
  - rate limiting triggers.

- **DB**:
  - connections;
  - slow queries;
  - реплікація (lag).

- **NATS/Event Bus**:
  - backlog per consumer;
  - delivery errors;
  - redeliveries.

- **Agents**:
  - кількість запусків;
  - середня тривалість run;
  - помилки агента (LLM/tool errors).

### 10.2 Логи

- централізований збір (ELK / Loki / Cloud Logging);
- кореляційні ID:
  - `X-Request-ID` на кожен HTTP-запит;
  - propagation у NATS payload (trace_id / correlation_id).

---

## 11. Backups & Restore

### 11.1 Backups

- Prod:
  - щоденні повні snapshots;
  - WAL / PITR (Point-In-Time Recovery) на 7–30 днів;
- Staging:
  - щоденні або раз на 2–3 дні (за потреби).

### 11.2 Restore Policy

- тестовий restore на окремий тимчасовий кластер мінімум раз на місяць;
- документований сценарій:
  - відновлення в новий кластер;
  - redirect трафіку (якщо потрібно).

---

## 12. Rollout Strategies

### 12.1 API/Backend

- **Canary**:
  - невеликий відсоток трафіку на новий реліз;
  - моніторинг помилок/латентності;
  - поступове збільшення.

- **Blue-Green**:
  - parallel stack (blue/green);
  - перемикання через load balancer/DNS.

### 12.2 Frontend

- атомарний switch build'ів (immutable artifacts);
- rollback = переключення на попередній build.

### 12.3 Feature Flags

- складні зміни (особливо агенти, Gift Fabric, RWA) — за feature flags:
  - flags зберігаються в БД або у спеціальному конфіг-сервісі;
  - викочуються спочатку на dev/staging, потім для частини користувачів у prod.

---

## 13. CI/CD Pipeline (Reference)

Псевдо-YAML для орієнтира:

```yaml
name: deploy

on:
  push:
    branches: [develop, main]
    tags: ['v*']

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run lint
      - run: npm test
      - run: npm run build:web
      - run: npm run build:api

  migrate-and-deploy:
    needs: build-and-test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run DB migrations
        run: |
          ./scripts/migrate.sh up
      - name: Deploy API
        run: |
          ./scripts/deploy_api.sh
      - name: Deploy Web
        run: |
          ./scripts/deploy_web.sh
```

---

## 14. Завдання для Cursor

```text
You are a senior DevOps engineer. Set up deployment infrastructure using:
- 25_deployment_infrastructure.md
- 27_database_schema_migrations.md
- 05_coding_standards.md

Tasks:
1) Create docker-compose.yml for local development (postgres, nats, minio).
2) Create CI/CD pipeline configuration (GitHub Actions / GitLab CI).
3) Create deployment scripts (migrate.sh, deploy_api.sh, deploy_web.sh).
4) Set up environment variable templates (.env.example).
5) Create monitoring dashboard configuration (Grafana / Prometheus).

Output:
- list of modified files
- diff
- summary
```

---

## 15. Результат

Після впровадження цієї інфраструктури:

- чітко визначені середовища та процеси деплою;
- стандартизований CI/CD pipeline;
- готовність до масштабування та production deployment;
- моніторинг та логування для всіх компонентів;
- надійні backup/restore процеси.

---

**Версія:** 1.0  
**Останнє оновлення:** 2024-11-14