Skip to content

# 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

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

1. User/Team Service
2. Messaging Service
3. Projects/Tasks Service
4. Agent Orchestrator
5. LLM Proxy Service
6. Router/Planner Service (DAARWIZZ)
7. Wallet Service
8. RWA Inventory Service
9. Embassy Gateway Service
10. Oracle Processor
11. Governance Service
12. Capability Registry Service
13. Quota/Usage Service
14. Outbox Worker
15. Telemetry/Logs Service
16. Auth/Session Service
17. 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