microdao-daarion/infrastructure/matrix-gateway

Matrix Gateway

Дата: 2026-01-10
Версія: 1.0.0

---

📋 Призначення

Matrix Gateway — компонент, який зв'язує Matrix rooms з NATS JetStream jobs:

1. Приймає команди з Matrix rooms (формат: !command args)
2. Перевіряє RBAC через Postgres
3. Створює jobs у NATS JetStream
4. Публікує статуси назад у Matrix

---

🔧 Команди

Підтримувані команди:

• !embed <text> — створює embedding job (online priority)
• !retrieve <query> — створює retrieval job (online priority)
• !summarize <thread_id> — створює summarization job (offline priority)

Приклад:

!embed Привіт, це тестовий текст для embedding

---

🚀 Deployment

K8s

kubectl apply -f infrastructure/kubernetes/matrix-gateway/deployment.yaml

Docker

docker build -t matrix-gateway:latest .
docker run -d \
  -e MATRIX_HOMESERVER=https://matrix.org \
  -e MATRIX_USER=@user:matrix.org \
  -e MATRIX_PASSWORD=password \
  -e MATRIX_ROOM_ID=!roomid:matrix.org \
  -e NATS_URL=nats://nats-client.nats:4222 \
  -e POSTGRES_URL=postgresql://... \
  matrix-gateway:latest

---

🔐 RBAC

RBAC перевірка виконується через таблицю matrix_rbac в Postgres:

CREATE TABLE matrix_rbac (
    user_id VARCHAR(255) PRIMARY KEY,
    permissions TEXT[] NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

Додавання користувача:

INSERT INTO matrix_rbac (user_id, permissions)
VALUES ('@user:matrix.org', ARRAY['execute_job', 'admin']);

---

📊 Архітектура

Matrix Room
    ↓
Matrix Gateway
    ├── RBAC Checker (Postgres)
    ├── Job Creator
    └── NATS Publisher
        ↓
NATS JetStream
    ├── MM_ONLINE (embed, retrieve, summarize)
    └── MM_OFFLINE (backfill, index)
        ↓
Worker Daemon
    └── Job Executor
        ↓
Memory Service / Qdrant / PostgreSQL

---

🔄 Потік виконання

1. Користувач відправляє команду в Matrix room: !embed текст
2. Matrix Gateway отримує повідомлення
3. RBAC перевірка: чи має користувач право execute_job?
4. Парсинг команди та створення job payload
5. Публікація job у NATS (subject: mm.embed.online)
6. Підтвердження в Matrix: ✅ Job створено: <job_id>
7. Worker Daemon бере job, виконує, пише результат
8. (Опціонально) Matrix Gateway публікує результат назад у Matrix

---

📁 Структура коду

gateway/
├── main.py              # Entry point
├── matrix_client.py     # Matrix connection & sync
├── nats_publisher.py    # NATS job publishing
├── rbac.py              # RBAC checking
└── job_creator.py       # Job creation from commands

---

Документ створено: 2026-01-10 19:30 CET