microdao-daarion/docs/NODE_INFRASTRUCTURE_STANDARDS.md

🏗️ Стандарти Інфраструктури НОД — 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

1. Code Sync: git pull origin main
2. ENV Check: Verify .env variables
3. DB Migrations: Apply sequentially
4. Build: docker compose build <service>
5. Start: docker compose up -d <service>
6. Health Check: Verify /health endpoint
7. Smoke Tests: Run basic API tests
8. 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