daarion-admin/microdao-daarion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c8698f6a1d449eb7f180253dee9a44a81310a5c0
microdao-daarion/docs/cursor/34_internal_services_architecture.md
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

680 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
```text
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
Reference in New Issue View Git Blame Copy Permalink