microdao-daarion/docs/internal/specs/matrix_presence_aggregator.md

Matrix Presence Aggregator Spec (v2)

Огляд

Aggregator збирає дані з Matrix Synapse + PostgreSQL (agents) і транслює їх через REST/SSE.

Потік даних

1. rooms_source читає city_rooms (matrix_room_id, координати).
2. agents_source читає agents (online/busy/offline, current_room_id).
3. MatrixClient полить членів кімнат (/_matrix/client/v3/rooms/.../members).
4. Presence API (/_matrix/client/v3/presence/.../status) → з Heartbeat hook у фронті.
5. Snapshot → GET /presence/summary, GET /presence/stream (SSE).

Формат Snapshot

{
  "type": "presence_update",
  "timestamp": "2025-11-27T15:10:00Z",
  "city": {
    "online_total": 7,
    "rooms_online": 4,
    "agents_online": 3
  },
  "rooms": [
    {
      "room_id": "room_city_general",
      "matrix_room_id": "!abc:daarion.space",
      "online": 5,
      "typing": 1,
      "agents": [ { "agent_id": "ag_atlas", "status": "online" } ]
    }
  ],
  "agents": [ ... ]
}

План розвитку

• Presence diffs (щоб зменшити трафік SSE).
• Aggregated analytics (average online per room).
• Події для Agent Presence v2 (агент перемістився).