# 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

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

### Docker

```bash
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:

```sql
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
);
```

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

```sql
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*