🏗️ Стандарти Інфраструктури НОД — DAARION Ecosystem¶

Версія: 1.0.0
Дата: 25 листопада 2025
Мета: Уніфікація архітектури на всіх нодах системи

🎯 Принципи¶

1. Consistency First¶

Кожна нода має однакову структуру каталогів, конфігів, портів (де можливо).

2. Isolation with Integration¶

Сервіси ізольовані (Docker), але інтегруються через стандартні протоколи (HTTP, WS, NATS).

3. Observable by Default¶

Кожна нода має Prometheus metrics + health endpoints.

4. Git as Source of Truth¶

Всі конфігурації та код в Git. Ніяких "ручних правок".

5. Rollback Ready¶

Кожен deployment має чіткий rollback plan.

📁 Стандартна Структура Ноди¶

/opt/microdao-daarion/  (або /Users/apple/github-projects/microdao-daarion/)
│
├── .env                        # Environment variables (не в Git!)
├── .env.example                # Template (в Git)
├── docker-compose.all.yml      # Головний compose file
├── docker-compose.dev.yml      # Dev overrides (опційно)
│
├── services/                   # Всі мікросервіси
│   ├── agents-service/
│   ├── city-service/
│   ├── secondme-service/
│   ├── router/
│   ├── gateway/
│   └── ...
│
├── migrations/                 # Database migrations
│   ├── 001_*.sql
│   ├── 002_*.sql
│   └── ...
│
├── scripts/                    # Automation scripts
│   ├── deploy-prod.sh
│   ├── backup-db.sh
│   ├── health-check.sh
│   └── rollback.sh
│
├── docs/                       # Documentation
│   ├── INFRASTRUCTURE.md
│   ├── DEPLOY_*.md
│   └── NODE_INFRASTRUCTURE_STANDARDS.md (цей файл)
│
├── infra/                      # Infrastructure configs
│   ├── nginx/
│   ├── prometheus/
│   ├── grafana/
│   └── caddy/ (якщо використовується)
│
└── backups/                    # Database backups (не в Git!)
    └── daarion_memory_*.sql

🔢 Стандартні Порти¶

Core Infrastructure¶

Service	Port	Protocol	Note
PostgreSQL	5432	TCP	Internal only
Redis	6379	TCP	Internal only
NATS	4222	TCP	Internal only
Prometheus	9090	HTTP	Monitoring
Grafana	3000	HTTP	Dashboards
Nginx/Gateway	80/443	HTTP/HTTPS	Public entry

DAGI Stack (Production)¶

Service	Port	Protocol	Note
Router	9102	HTTP	DAGI Router
Gateway	9300	HTTP	Bot Gateway
DevTools	8008	HTTP	Dev Interface
Swapper	8890-8891	HTTP	Model Swapper + Metrics
Frontend	8899	HTTP	Web UI

Phase 1-3 MVP Services¶

Service	Port	Protocol	Note
City Service	7001	HTTP + WS	Public Rooms + Presence
Agents Service	7002	HTTP	Agent Core
Second Me	7003	HTTP	Personal AI
MicroDAO Service	7004	HTTP	MicroDAO Core

Multimodal Services (НОДА2 initially)¶

Service	Port	Protocol	Note
STT Service	8895	HTTP	Speech-to-Text
OCR Service	8896	HTTP	Image-to-Text
Web Search	8897	HTTP	Search Engine
Vector DB	8898	HTTP	Semantic Search

Правило: Порти 7000-7999 — MVP services, 8000-8999 — Utilities/Multimodal, 9000-9999 — DAGI Stack.

🌐 API Routing Standards¶

Через Nginx/Gateway¶

https://<domain>/api/<service>/<endpoint>

Приклади:

https://gateway.daarion.city/api/agents/list
https://gateway.daarion.city/api/city/rooms
https://gateway.daarion.city/api/secondme/invoke
https://gateway.daarion.city/api/microdao/members

WebSocket¶

wss://<domain>/ws/<service>/<channel>

Приклади:

wss://gateway.daarion.city/ws/city/rooms/general
wss://gateway.daarion.city/ws/city/presence
wss://gateway.daarion.city/ws/agents/events

🐳 Docker Standards¶

Naming Convention¶

Containers:

<project>-<service>

Examples: - daarion-postgres - daarion-agents-service - daarion-city-service

Networks:

<project>_net

Example: - daarion_net

Volumes:

<service>_data

Examples: - postgres_data - redis_data - nats_data

Labels (для моніторингу)¶

services:
  agents-service:
    labels:
      - "com.daarion.service=agents"
      - "com.daarion.tier=backend"
      - "com.daarion.phase=mvp"

📊 Health Check Standards¶

Endpoint¶

Кожен сервіс ОБОВ'ЯЗКОВО має endpoint:

GET /health

Response:

{
  "status": "healthy",
  "service": "agents-service",
  "version": "1.0.0",
  "uptime": 3600,
  "dependencies": {
    "database": "connected",
    "redis": "connected",
    "nats": "connected"
  }
}

Status Codes: - 200 — Healthy - 503 — Unhealthy (service degraded)

Docker Healthcheck¶

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:7002/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s

📈 Metrics Standards (Prometheus)¶

Endpoint¶

GET /metrics

Format: Prometheus text format

Required Metrics:

# HTTP requests
http_requests_total{service="agents",method="GET",status="200"} 1234

# Response time
http_request_duration_seconds_bucket{le="0.1"} 100

# Active connections
active_connections{service="agents"} 42

# Health status
service_health{service="agents",dependency="database"} 1

🔐 Security Standards¶

1. Secrets Management¶

НЕ В GIT: - .env файли з паролями - SSL приватні ключі - API tokens - DB passwords

В GIT: - .env.example з плейсхолдерами - Public SSL certificates (якщо потрібно)

2. Network Isolation¶

services:
  postgres:
    networks:
      - daarion_net
    # НЕ expose ports на host!

Тільки gateway має публічні порти:

services:
  gateway-nginx:
    ports:
      - "80:80"
      - "443:443"

3. Rate Limiting¶

Nginx має rate limiting для API:

limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;

location /api/ {
    limit_req zone=api_limit burst=20 nodelay;
}

🗄️ Database Standards¶

Migrations¶

Naming:

XXX_description.sql

Examples: - 001_create_messenger_schema.sql - 007_create_agents_tables.sql - 010_create_city_backend.sql

Header (у кожній міграції):

-- Migration: 007
-- Description: Create agents tables
-- Date: 2025-11-20
-- Author: DAARION Team
-- Rollback: See 007_rollback.sql

BEGIN;

-- Your changes here

COMMIT;

Backup Schedule¶

Production (НОДА1): - Щоденно о 03:00 UTC - Зберігати останні 7 днів - Weekly backup (зберігати 4 тижні)

Commands:

# Backup
docker exec daarion-postgres pg_dump -U postgres daarion_memory > \
  /root/backups/daarion_memory_$(date +%Y%m%d_%H%M%S).sql

# Restore
docker exec -i daarion-postgres psql -U postgres -d daarion_memory < \
  /root/backups/daarion_memory_YYYYMMDD_HHMMSS.sql

🔄 Deployment Standards¶

Pre-Deployment Checklist¶

[ ] Git branch merged to main
[ ] All tests passed (якщо є)
[ ] Database backup created
[ ] Health checks passing on staging/dev
[ ] Rollback plan documented
[ ] Team notified (якщо production)

Deployment Process¶

Code Sync: git pull origin main
ENV Check: Verify .env variables
DB Migrations: Apply sequentially
Build: docker compose build <service>
Start: docker compose up -d <service>
Health Check: Verify /health endpoint
Smoke Tests: Run basic API tests
Monitor: Watch logs for 5-15 minutes

Post-Deployment¶

[ ] Health checks passing
[ ] Metrics appearing in Prometheus
[ ] No critical errors in logs
[ ] Existing services unaffected
[ ] Update INFRASTRUCTURE.md

📝 Logging Standards¶

Log Format (JSON)¶

{
  "timestamp": "2025-11-25T10:30:00Z",
  "level": "INFO",
  "service": "agents-service",
  "message": "Agent invoked",
  "agent_id": "ag_123",
  "user_id": "u_456",
  "request_id": "req_789"
}

Log Levels¶

DEBUG — Детальна інформація (тільки в dev)
INFO — Нормальні операції
WARNING — Потенційна проблема
ERROR — Помилка яку треба перевірити
CRITICAL — Система не працює

Centralized Logging (майбутнє)¶

Варіанти: - Grafana Loki - ELK Stack - CloudWatch (якщо AWS)

🌍 Multi-Node Standards¶

Node Roles¶

Node	Role	Uptime	Services
НОДА1	Production	24/7	All Core + MVP
НОДА2	Dev + Backup	On-demand	Core + Multimodal
НОДА3 (майбутнє)	Federation	24/7	Matrix + City

Service Distribution¶

Production (НОДА1): - Router, Gateway, DevTools - Agents, City, Second Me, MicroDAO - PostgreSQL, Redis, NATS - Monitoring (Prometheus, Grafana)

Development (НОДА2): - Core services (для тестування) - Multimodal services (STT, OCR, Web Search, Vector DB) - Experimental features

Federation (НОДА3, майбутнє): - Matrix Synapse - City Federation - DAO Governance

Cross-Node Communication¶

Через публічні API:

NODE1 → NODE2
https://node2.local:8897/api/search (Web Search)

Через VPN/WireGuard (майбутнє):

NODE1 ←→ NODE2 ←→ NODE3
10.0.0.1   10.0.0.2   10.0.0.3

🔮 Future Standards (Roadmap)¶

Phase MULTI (Multimodal Integration)¶

[ ] Router v2.0 з multimodal підтримкою
[ ] Unified API для всіх multimodal сервісів
[ ] Fallback mechanisms (якщо НОДА2 offline)

Phase MATRIX (Federation)¶

[ ] Matrix Synapse на НОДА3
[ ] Element Web client integration
[ ] NATS ↔ Matrix bridge

Phase SCALE (Horizontal Scaling)¶

[ ] Load balancer перед нодами
[ ] Auto-scaling для сервісів
[ ] Distributed cache (Redis Cluster)

Phase MONITOR (Advanced Monitoring)¶

[ ] Distributed tracing (Jaeger/Tempo)
[ ] APM (Application Performance Monitoring)
[ ] Alerting (Alertmanager)

📞 Contacts & Resources¶

Documentation: - Main: /docs/INFRASTRUCTURE.md - Quick Ref: /docs/infrastructure_quick_ref.ipynb - Deployment: /docs/DEPLOY_*.md

GitHub: - Main Repo: git@github.com:IvanTytar/microdao-daarion.git - DAARION City: git@github.com:DAARION-DAO/daarion-ai-city.git

Monitoring: - Prometheus: http://localhost:9090 - Grafana: http://localhost:3000

✅ Compliance Checklist¶

Кожна нода має: - [ ] Стандартна структура каталогів - [ ] Docker Compose з усіма сервісами - [ ] Health endpoints на всіх сервісах - [ ] Prometheus metrics - [ ] Backup strategy - [ ] Rollback plan - [ ] Nginx/Gateway з SSL - [ ] .env не в Git - [ ] Документація актуальна

Документ створено: Cursor AI Assistant
Для проєкту: MicroDAO DAARION
Останнє оновлення: 2025-11-25