# 🏗️ Стандарти Інфраструктури НОД — 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:///api// ``` **Приклади:** ``` 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:///ws// ``` **Приклади:** ``` 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:** ``` - ``` **Examples:** - `daarion-postgres` - `daarion-agents-service` - `daarion-city-service` **Networks:** ``` _net ``` **Example:** - `daarion_net` **Volumes:** ``` _data ``` **Examples:** - `postgres_data` - `redis_data` - `nats_data` ### Labels (для моніторингу) ```yaml services: agents-service: labels: - "com.daarion.service=agents" - "com.daarion.tier=backend" - "com.daarion.phase=mvp" ``` --- ## 📊 Health Check Standards ### Endpoint Кожен сервіс **ОБОВ'ЯЗКОВО** має endpoint: ``` GET /health ``` **Response:** ```json { "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 ```yaml 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** ```yaml services: postgres: networks: - daarion_net # НЕ expose ports на host! ``` **Тільки gateway має публічні порти:** ```yaml services: gateway-nginx: ports: - "80:80" - "443:443" ``` ### 3. **Rate Limiting** Nginx має rate limiting для API: ```nginx 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 (у кожній міграції):** ```sql -- 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:** ```bash # 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 ` 5. **Start:** `docker compose up -d ` 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) ```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