34 — Internal Services Architecture (MicroDAO)¶

Архітектура внутрішніх сервісів, їхні ролі, API, дані, залежності, взаємодія з PDP, Gateway, NATS, DB

1. Purpose & Scope¶

Цей документ описує:

які внутрішні сервіси існують,
їхню відповідальність,
текучку даних,
API кожного сервісу,
які таблиці вони контролюють,
які події вони публікують у NATS,
залежності між сервісами,
що можна відокремити у мікросервіси, а що залишити монолітом,
їх роль у масштабуванні та HA.

Це карта всіх backend-компонентів DAARION.city.

2. High-Level Service Landscape¶

                      ┌──────────────────────────┐
                      │    API Gateway (PEP)     │
                      └───────────────┬──────────┘
                                      │
                   ┌──────────────────┴──────────────────┐
                   │                                     │
           Public API                            Internal Service Mesh

Внутрішні сервіси:

User/Team Service
Messaging Service
Projects/Tasks Service
Agent Orchestrator
LLM Proxy Service
Router/Planner Service (DAARWIZZ)
Wallet Service
RWA Inventory Service
Embassy Gateway Service
Oracle Processor
Governance Service
Capability Registry Service
Quota/Usage Service
Outbox Worker
Telemetry/Logs Service
Auth/Session Service
File Storage/Docs Service

Усі сервіси є modular, але можуть бути реалізовані або як microservices, або як modular monolith.

3. Core Principles¶

Stateless там, де можливо → просте масштабування.
Stateful там, де потрібно (wallet, RWA) → обережні транзакції.
Event-driven через NATS.
PDP-централізована авторизація.
Outbox pattern для гарантій доставки подій.
Strong ACID тільки на критичних таблицях.
Soft eventual-consistency на неважливих частинах.

4. Internal Services Overview¶

4.1 User & Team Service¶

Відповідальність:¶

Users, teams, memberships.
Roles: Owner, Guardian, Member, Visitor.
Viewer types: reader/commenter/contributor.
Team mode: public/confidential.

Таблиці:¶

users
teams
team_members

API (internal):¶

GET /internal/team/:id
POST /internal/team/create
POST /internal/team/member/add
POST /internal/team/member/remove

Події (NATS):¶

team.member.joined
team.member.left

4.2 Messaging Service¶

Відповідальність:¶

Channels, messages, followups.
Co-memory embeddings.
Confidential mode enforcement (via Gateway).

Таблиці:¶

channels
messages
followups
comemory_items

API:¶

POST /internal/message/send
GET /internal/channel/:id/messages
POST /internal/comemory/index

Події:¶

chat.message.created
comemory.item.created

4.3 Projects & Tasks Service¶

Відповідальність:¶

Projects, tasks, workflow.

Таблиці:¶

projects
tasks

Події:¶

project.created
task.created
task.updated

4.4 Agent Orchestrator¶

Відповідальність:¶

запуск приватних агентів;
трекінг agent_runs;
sandbox execution.

Таблиці:¶

agents
agent_runs

Події:¶

agent.run.started
agent.run.completed

API:¶

POST /internal/agent/run
POST /internal/agent/finish
GET /internal/agent/run/:id/status

4.5 LLM Proxy Service¶

Завдання:¶

централізований доступ до LLM (OpenAI / local models).
облік токенів.
нормалізація моделей.

API:¶

POST /internal/llm/chat
POST /internal/llm/embeddings

Event:¶

llm.tokens.used

4.6 Router / Planner (DAARWIZZ)¶

Відповідальність:¶

run multi-agent routing pipeline;
orchestration of tools;
intent recognition;
complex "flows".

API:¶

POST /internal/router/route
POST /internal/router/plan

Events:¶

router.invoked
router.completed

4.7 Wallet Service¶

Відповідальність:¶

стейк RINGK;
генерація payout'ів;
claim payout;
зв'язок з блокчейном.

Таблиці:¶

wallets
staking_ringk
payouts

API:¶

POST /internal/wallet/stake
POST /internal/wallet/payout/claim
GET /internal/wallet/balance/:user

Events:¶

staking.locked
payout.generated
payout.claimed

4.8 RWA Inventory Service¶

Відповідальність:¶

облік energy/food/water/etc.
інтеграція з Embassy.
оновлення RWA стоків.

Таблиці:¶

rwa_inventory

Events:¶

rwa.inventory.updated

4.9 Embassy Gateway Service¶

Відповідальність:¶

прийом підписаних webhook'ів від платформ (EnergyUnion, GREENFOOD).
HMAC перевірка.
PDP авторизація (embassy keys).
генерація подій для NATS.

Таблиці:¶

embassy_identities
embassy_webhooks

API:¶

POST /embassy/energy
POST /embassy/rwa

Events:¶

embassy.event.received
embassy.energy.update
embassy.rwa.claim

4.10 Oracle Processor¶

Відповідальність:¶

обробка потоків енергетичних даних;
нормалізація;
створення oracles.

Таблиці:¶

oracles

Events:¶

oracle.reading.published

4.11 Governance Service¶

Відповідальність:¶

пропозиції,
голосування,
застосування політик,
оновлення bundles/caps/quotas.

Таблиці:¶

governance_policies

Events:¶

governance.policy.updated

4.12 Capability Registry Service¶

Відповідальність:¶

управління:
capabilities,
bundles,
bundle_caps,
plan entitlements.

Таблиці:¶

capabilities
bundles
bundle_caps
access_keys
access_key_caps

4.13 Usage Service¶

Відповідальність:¶

підрахунок usage:
agent runs,
LLM tokens,
embassy events,
router invokes,
wallet transactions.

Таблиці:¶

(опціонально)

usage_agent_runs
usage_llm
usage_storage
usage_router

Або ж використовує event-driven pipeline.

4.14 Outbox Worker¶

Відповідальність:¶

читання outbox_events з БД;
публікація у NATS;
маркування processed.

Таблиця:¶

outbox_events

4.15 Telemetry / Logs Service¶

Відповідальність:¶

прийом логів з фронтенду,
прийом internal logs,
агрегація в аналітичні стріми.

Events:¶

telemetry.client.event
telemetry.error
telemetry.screen_view

4.16 Auth / Session Service¶

Відповідальність:¶

login,
OTP/Magic-link,
session cookies.

Таблиці:¶

sessions (опціонально)

4.17 File Storage / Docs Service¶

Відповідальність:¶

завантаження файлів у каналах,
документи,
архіви,
прев'ю.

Технічно:

Minio/S3 + Postgres references.

5. Dependency Graph¶

Умовний граф залежностей:

User/Team → Messaging → Projects/Tasks → Agents → Router
                    ↓            ↓        ↓
                 RWA       Wallet       Embassy
                    ↓           ↓         ↓
                  Oracle → Usage → Governance → PDP

Простіший вигляд:

API Gateway (PEP)
      ↓ PDP
      ↓
Internal Services
      ↓
DB + NATS

6. Internal API Standards¶

Всі внутрішні сервіси мають:

JSON-only API,
версію /internal/v1/...,
заборона на виклик ззовні (тільки з Gateway),
сервісні ключі (internal service key),
PDP перевіряє internal capabilities:
service.mint.payout
service.write.oracles
service.update.capabilities
service.read.internal_logs

7. Horizontal Scaling Responsibilities¶

Stateless services:¶

Messaging
Projects/Tasks
Embassy Gateway
Telemetry
Router/Planner (частково)
LLM Proxy

Stateful services:¶

Wallet
RWA
Governance
Capability Registry
Usage Service (підрахунок)

8. Event Streams (NATS Topics)¶

chat.*

project.*

task.*

agent.run.*

embassy.*

oracle.*

rwa.inventory.*

wallet.*

governance.*

usage.*

telemetry.*

9. Outbox Pattern (Mandatory)¶

Всі сервіси, що створюють події:

пишуть у outbox_events (processed=false),
Outbox Worker публікує у NATS,
записує processed=true.

Це гарантує at-least-once delivery.

10. Cross-service Transaction Rules¶

Дозволені:

DB transaction → outbox insert → commit
Outbox Worker → publish event

Заборонені:

DB transaction → direct NATS publish → commit
Cross-service DB транзакції

11. Security Boundaries¶

Service	Sensitive?	Notes
Wallet	HIGH	Chain operations, payouts
Embassy	HIGH	RWA, energy events
Capability Registry	HIGH	controls all access
Governance	HIGH	updates policies
Usage	MEDIUM	affects quotas
Agents	MEDIUM	potential abuse
Messaging	MEDIUM	privacy
Router	HIGH	tool access
LLM Proxy	HIGH	cost centre

12. Suggested Deployment Model¶

Option A — Modular Monolith (MVP)¶

Окремі модулі всередині одного репозиторію.

Переваги:

мінімальні затрати,
простий деплой,
контроль consistency.

Option B — Microservices (Prod-Scale)¶

Розділяються:

Wallet,
Embassy,
Router,
LLM Proxy,
Agent Orchestrator,
Messaging,
Projects,
Governance,
Capability Registry,
Usage.

13. Failure Isolation¶

Сервіс повинен не ламати інших.

Наприклад:

Wallet падає → Messaging працює далі.
Embassy перевантажений → Agent Runs працюють.
Router overloaded → Wallet стабільний.

Це досягається:

NATS,
independent autoscaling,
clear API boundaries.

14. Minimal Monitoring Set per Service¶

Для кожного:

CPU/Memory
Requests/sec
Error rate
Latency
DB queries
NATS event lag
Circuit breaker status
Quota usage

15. Integration with Other Docs¶

Цей документ доповнює:

33_api_gateway_security_and_pep.md
32_policy_service_PDP_design.md
29_scaling_and_high_availability.md
28_flows_wallet_embassy_energy_union.md
27_database_schema_migrations.md

16. Завдання для Cursor¶

You are a senior backend architect. Design internal services architecture using:
- 34_internal_services_architecture.md
- 33_api_gateway_security_and_pep.md
- 32_policy_service_PDP_design.md

Tasks:
1) Create service interfaces for all 17 services.
2) Define internal API contracts.
3) Implement Outbox Worker for event publishing.
4) Set up NATS event streams for all services.
5) Create service discovery mechanism (if microservices).
6) Implement cross-service communication patterns.
7) Add monitoring and observability for each service.

Output:
- list of modified files
- diff
- summary

17. Summary¶

Цей документ задає основу:

хто за що відповідає,
які дані де живуть,
які події кожен сервіс генерує,
як сервіси взаємодіють,
де потрібна строгість ACID,
як працює event-driven архітектура,
де є stateful точки опори.

Це ключова частина всієї backend-карти міста.

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