microdao-daarion/services/city-service

🏙️ DAARION City Service

Версія: 1.0.0
Статус: Development (Mock Data)
Порт: 7001

---

📋 Опис

City Service — це агрегатор даних для City Dashboard в екосистемі DAARION. Збирає та об'єднує інформацію з різних джерел для створення повного знімку стану міста.

Функціонал

• 📊 City Snapshot — повний знімок стану міста
• 👤 User Context — профіль користувача та archetype
• 🏛️ MicroDAO State — стан microDAO користувача
• 📈 Metrics Aggregation — глобальні метрики міста
• 🖥️ Node Status — стан усіх нод
• 🤖 Agent Presence — активні агенти
• 🎯 Quests — активні квести
• 📡 Events Feed — останні події міста

---

🚀 Швидкий старт

Через Docker Compose

# З кореня проєкту
./scripts/start-city-space-services.sh

Локально (Development)

cd services/city-service

# Створити віртуальне середовище
python -m venv venv
source venv/bin/activate  # Linux/Mac
# або venv\Scripts\activate  # Windows

# Встановити залежності
pip install -r requirements.txt

# Запустити сервіс
python main.py

# Або через uvicorn
uvicorn main:app --reload --port 7001

---

📡 API Endpoints

GET /health

Health check endpoint

Response:

{
  "status": "healthy",
  "service": "city-service"
}

---

GET /api/city/snapshot

Повертає повний знімок стану міста DAARION

Response: CitySnapshot

{
  "user": {
    "id": "user:93",
    "handle": "@alice:daarion.city",
    "archetype": "Explorer",
    "microdaoId": "microdao:7"
  },
  "microdao": {
    "id": "microdao:7",
    "name": "Quantum Garden",
    "members": 7,
    "humans": 4,
    "agents": 3,
    "balanceDcr": 12820,
    "activity24h": 0.84
  },
  "metrics": {
    "activityIndex": 0.71,
    "avgAgentLatencyMs": 13,
    "natsTps": 48200,
    "nodeAvgLoad": 0.66,
    "errorRate": 0.009,
    "questEngagement": 0.62
  },
  "nodes": [...],
  "agents": [...],
  "quests": [...],
  "events": [...]
}

---

🗺️ Схема агрегації даних

┌─────────────────────────────────────────────────────────┐
│                   City Service                          │
│                  (Port: 7001)                           │
└─────────────────────────────────────────────────────────┘
                         │
         ┌───────────────┼───────────────┐
         │               │               │
         ▼               ▼               ▼
┌─────────────┐  ┌─────────────┐  ┌──────────────┐
│   Auth /    │  │  microDAO   │  │   Metrics    │
│  Profile    │  │   Service   │  │  Collector   │
│   Service   │  │             │  │              │
└─────────────┘  └─────────────┘  └──────────────┘
                                          │
                 ┌────────────────────────┤
                 │                        │
                 ▼                        ▼
         ┌──────────────┐         ┌──────────────┐
         │ NATS         │         │ Redis /      │
         │ JetStream    │         │ Timescale    │
         └──────────────┘         └──────────────┘
                 │
         ┌───────┴────────┐
         │                │
         ▼                ▼
┌──────────────┐  ┌──────────────┐
│ NodeMetrics  │  │ Agent        │
│ Agent        │  │ Registry     │
└──────────────┘  └──────────────┘

---

📊 Джерела даних

Поле	Джерело	NATS Subject
user	Auth / Profile service	user.profile.*
microdao	microDAO service	microdao.state.*
metrics	Metrics collector (NATS → Redis/TSDB)	metrics.city.*
nodes	NodeMetrics Agent (NATS node.metrics.*)	node.metrics.*
agents	Agent Registry	agent.status.*
quests	Quest Engine	quest.active.*
events	JetStream Stream events.city.*	events.city.*

---

🔧 Конфігурація

Environment Variables

# Service
LOG_LEVEL=INFO
ENVIRONMENT=development

# Redis (для кешу метрик)
REDIS_URL=redis://redis:6379

# NATS (для підписки на події)
NATS_URL=nats://nats:4222

# PostgreSQL (для user/microDAO даних)
DATABASE_URL=postgresql://postgres:postgres@postgres:5432/daarion

# CORS
CORS_ORIGINS=http://localhost:8899,https://daarion.city

---

🏗️ Структура проєкту

services/city-service/
├── main.py              # FastAPI application
├── requirements.txt     # Python dependencies
├── Dockerfile          # Docker image
├── README.md           # Ця документація
├── models/             # Pydantic models (TODO)
│   ├── __init__.py
│   ├── city.py
│   └── response.py
├── services/           # Business logic (TODO)
│   ├── __init__.py
│   ├── aggregator.py   # Data aggregation
│   ├── nats_client.py  # NATS integration
│   └── redis_client.py # Redis integration
└── tests/              # Unit tests (TODO)
    ├── __init__.py
    └── test_api.py

---

🧪 Тестування

# Health check
curl http://localhost:7001/health

# Get city snapshot
curl http://localhost:7001/api/city/snapshot

# Через API Gateway
curl http://localhost:8080/api/city/snapshot

Expected Response Time

• /health: < 10ms
• /api/city/snapshot: < 100ms (з кешем)

---

📈 Моніторинг

Health Checks

# Docker health check
docker inspect daarion-city-service | grep Health

# Manual health check
curl -f http://localhost:7001/health || exit 1

Logs

# Follow logs
docker logs -f daarion-city-service

# Last 100 lines
docker logs --tail 100 daarion-city-service

Metrics (TODO)

• Prometheus endpoint: /metrics
• Grafana dashboard: City Service Overview

---

🚨 Troubleshooting

Service not starting

# Check logs
docker logs daarion-city-service

# Rebuild
docker-compose -f docker-compose.city-space.yml up -d --build city-service

CORS errors

# Check CORS_ORIGINS environment variable
docker exec daarion-city-service env | grep CORS

Slow response times

• Перевір з'єднання з Redis
• Перевір з'єднання з NATS
• Переглянь логи для помилок агрегації

---

🗺️ Roadmap

Phase 1: Mock Data ✅

• FastAPI application
• Mock city snapshot
• OpenAPI documentation
• Docker setup

Phase 2: Real Data Integration (Current)

• NATS client integration
• Redis client integration
• PostgreSQL integration
• Real-time metrics aggregation
• User profile integration
• MicroDAO state integration

Phase 3: WebSocket Support

• /ws/city — real-time city updates
• /ws/events — event stream
• /ws/metrics — live metrics

Phase 4: Optimization

• Response caching
• Query optimization
• Load testing
• Horizontal scaling

---

📚 Документація

• OpenAPI Docs: http://localhost:7001/docs
• ReDoc: http://localhost:7001/redoc
• OpenAPI JSON: http://localhost:7001/openapi.json

---

🤝 Contributing

1. Створи feature branch
2. Додай тести
3. Оновити документацію
4. Створи PR

---

📄 License

Proprietary — DAARION Ecosystem

---

📞 Контакти

• Maintainer: DAARION Core Team
• Issues: GitHub Issues
• Slack: #city-service