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
This commit is contained in:
Apple
679
docs/cursor/34_internal_services_architecture.md
Normal file
679
docs/cursor/34_internal_services_architecture.md
Normal file
@@ -0,0 +1,679 @@
|
||||
# 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
Block a user