Files

Apple c552199eed chore: organize documentation structure for monorepo

- Create /docs structure (microdao, daarion, agents)
- Organize 61 cursor technical docs
- Add README files for each category
- Copy key documents to public categories
- Add GitHub setup instructions and scripts

2025-11-15 04:08:35 -08:00

12 KiB

Raw Blame History

29 — Scaling & High Availability (MicroDAO)

Масштабування, відмовостійкість, балансування навантаження, кластеризація сервісів DAARION.city / microDAO / Embassy / Wallet / Agents / Event Bus

Це документ виробничого класу, який потрібний для:

архітекторів,
SRE,
DevOps,
інженерів, що відповідають за HA (High Availability),
аудиторів, які перевіряють стійкість платформи.

Він відповідає на питання:

як масштабуються сервіси;
як забезпечується відмовостійкість;
як працюють кластери (Postgres, NATS, агентна мережа);
як працює автоматичне масштабування;
як відбувається failover;
як відновлюється місто після аварій.

1. Objectives

Платформа DAARION.city має підтримувати:

Високу доступність (HA) SLA: 99.5%–99.9% залежно від сервісу.
Горизонтальне масштабування Чат, агенти, Embassy події, обробка RWA, NATS — мають масштабуватись окремо.
Event-driven архітектуру Потоки через NATS/JetStream.
Автоматичне відновлення після збоїв (self-healing).
Zero-downtime деплой.

2. High-level Architecture Overview

                     ┌─────────────────────────┐
                     │     Load Balancer        │
                     └──────────┬──────────────┘
                                │
                  ┌─────────────┴──────────────┐
                  │      API Gateway (PEP)      │
                  └─────────────┬──────────────┘
                                │
          ┌──────────────┬────────────┬──────────────┐
          │               │            │               │
      Messaging       Agents       Embassy         Wallet/RWA
      Service         Runtime      Gateway          Service
       (stateless)    (scalable)   (stateless)      (state + events)

                     ┌────────────────┐
                     │   NATS Cluster │
                     └────────────────┘
                              │
                    ┌───────────────────┐
                    │    Postgres HA    │
                    └───────────────────┘

Основний принцип — кожен домен масштабується автономно.

3. API Layer Scaling

3.1 API Gateway / Edge Functions

Stateless
Горизонтальне масштабування без обмежень
Auto-scaling подіями:
- RPS,
- latency,
- CPU,
- queue length

3.2 Failover

Health-check endpoints
LB прибирає unhealthy інстанси
Blue-Green або Canary rollout

4. Backend Domain Services Scaling

Статус сервісів DAARION:

Service	State	Scale Mode
Messaging	Stateless	Horizontal
Projects/Tasks	Stateless	Horizontal
Agent Orchestrator	Stateful (DB)	Horizontal (idempotent processing)
Wallet	Stateful	Horizontal (through DB locking, NATS ordering)
Embassy	Stateless	Horizontal
Telemetry	Stateless	Horizontal

4.1 Stateless Services

Messaging
Channels
Projects
Embassy Gateway
Telemetry
Governance API

Масштабуються лінійно кількістю інстансів.

4.2 Stateful Services

🔹 Wallet Service

Потребує:

row-level locks для payout.claim
idempotent payout.generated
deduplicated NATS consumer

🔹 Agent Orchestrator

Потребує:

«at least once» NATS delivery
run-idempotency (agent_runs.id)
partitioning agent runs

5. Agents Scaling

5.1 Типи агентів

Private agents (per-user/team)
Global agents (Router / Planner / Observer)
Embassy agents (interpreters for RWA)

5.2 Як вони масштабуються

User → API → enqueue → Agent Runtime Pool

Agent Runtime Pool:

десятки/сотні ізольованих воркерів;
один агент run не блокує інші;
автоматичний autoscaling від:
- queue depth,
- throughput,
- LLM latency.

5.3 Isolation Model

Для кожного агентного run:

окремий підпроцес / worker / container
можливість sandbox-обмеження

6. NATS JetStream Scaling & HA

6.1 Кластер

Рекомендована конфігурація для прод:

3 або 5 вузлів JetStream
Replication Factor = 3 для стрімів
Consumer durability = durable=true
Ack policy = explicit

6.2 Потоки (streams)

Структура тем:

chat.*
project.*
task.*
agent.run.*
wallet.*
embassy.*
oracle.*
rwa.*
governance.*
audit.*

6.3 Failure Scenarios

Failure	Наслідок	Відновлення
1 вузол падає	Кворум зберігається	Автоматичний failover
2 вузли падають (із 3)	Стрім read-only	Зберегти дані, обмеження на writes
Корупція стріму	Канарний споживач	Auto-resync

7. Postgres High Availability

7.1 Архітектура

Primary + at least 1–2 replicas
Synchronous replication (якщо SLA 99.9)
Архівування WAL (PITR)
Автоматичний failover (pg_auto_failover або cloud-managed)

7.2 Таблиці з високими вимогами до консистентності

wallets
staking_ringk
payouts
rwa_inventory
access_keys
bundles
outbox_events

Ці таблиці не допускають eventual consistency.

7.3 Query Optimization

Index coverage for all hot-path queries
Partitioning (опційно) для:
- messages
- audit_log
- outbox_events

8. Outbox Pattern Scaling

8.1 Worker Pool

2–10 воркерів
Кожен бере порцію подій
Події після обробки маркуються processed=true

8.2 Guarantees

At least once
Ordering controlled by:
- Partition key (team_id)
- Consumer group

8.3 Failure Mode

Pod kill → worker restarts → resumes work
network flap → events re-delivered
consumer crash → DLQ (dead letter queue)

9. Embassy Scaling

9.1 Incoming Webhooks

Stateless API
Unlimited horizontal scaling
Signature verification CPU-cheap

9.2 Oracle bursts

Embassy може отримати "бурст" даних з Energy Union:

10k–100k meter readings
обробляється пакетно
Embassy → NATS → Wallet Service

Wallet Service має бути autoscaled:

CPU > 70%
NATS consumer lag > threshold

10. Wallet Scaling & RWA

10.1 Ключові вимоги

Wallet Service обробляє:

payouts,
claims,
chain transactions,
RWA reward distribution.

Системні вимоги:

row-level lock на payouts при claim
mutex на chain transaction
idempotent TX submission

10.2 Autoscaling Logic

↑ CPU (chain operations heavy)
↑ NATS lag (payouts generated faster than processed)
↑ pending claim queue

11. Scaling Frontend

11.1 Static hosting

CDN кешування
SSR вимикається для важких сторінок (агентів, wallets)

11.2 Global edge distribution

географічні PoP
розподіл:
- US-EAST
- EU
- South America
- Asia

11.3 Feature Flag Rollout

мінімізація ризику на проді
partial enablement

12. Failover Strategies

12.1 API Layer

LB → автоматична заміна unhealthy nodes
Canary release на 5–10%

12.2 Postgres

автоматичний failover на replica
DNS/IP switch

12.3 NATS

внутрішня виборність leader
replica quorum

12.4 Agents

job requeue → new worker takes over

12.5 Embassy

stateless → fail instantly

12.6 Wallet

idempotent DB writes → rescue after crash

13. Disaster Recovery (DR)

13.1 Scenarios

Data center outage
Corrupted WAL / snapshot
Global cloud outage (provider-wide)
Stuck NATS cluster
Chain RPC outage
Embassy key leak
Agent DDOS / infinite loops

13.2 Recovery Plan

Hot standby region (multi-region Postgres)
Backup event bus
Secondary RPC provider
Embassy secrets rotation
Agent Sandbox re-creation

13.3 DR Tests

щоквартальні DR-ротації
restore Postgres snapshot
swap RPC endpoints
revoke all Embassy keys

14. Benchmark Targets

Компонент	Ціль
Messages	500 msg/sec
Agent runs	30–100 runs/min/worker
Embassy	1000 webhook/sec
Wallet payouts	50 payout/sec
NATS throughput	20k–50k events/sec
Postgres	p95 < 100 ms

15. Завдання для Cursor

You are a senior DevOps/SRE engineer. Implement HA infrastructure using:
- 29_scaling_and_high_availability.md
- 25_deployment_infrastructure.md
- 26_security_audit.md

Tasks:
1) Set up Postgres HA with automatic failover.
2) Configure NATS JetStream cluster (3-5 nodes).
3) Implement autoscaling for API Gateway and domain services.
4) Set up health checks and monitoring for all services.
5) Implement Outbox Worker pool with proper scaling.
6) Configure load balancer with health checks.
7) Set up disaster recovery procedures.

Output:
- list of modified files
- diff
- summary

16. Summary

Архітектура підтримує HA та autoscaling на кожному шарі.
Сервіси ізольовані за доменами.
NATS та Postgres у кластерному режимі.
Wallet / RWA / Embassy — найбільш критичні частини.
Масштабування агентів окреме, з autoscaling та sandbox isolation.
Готова база для prod-grade розгортання.

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

12 KiB Raw Blame History Unescape Escape