# Telegram Infrastructure

Мінімальний стек для інтеграції Telegram-ботів з системою агентів DAGI/microDAO.

## 🏗️ Архітектура

Цей стек складається з трьох сервісів:

### 1. **telegram-bot-api** (Local Telegram Bot API)
- Офіційний Local Telegram Bot API від Telegram
- Працює в режимі `--local` (HTTP only, без SSL)
- Доступний тільки на `127.0.0.1:8081` (не публічний)
- Дозволяє використовувати Bot API без зовнішніх запитів до Telegram серверів

### 2. **nats** (Message Bus)
- NATS як шина подій між сервісами
- Простий режим без кластера
- Доступний на `127.0.0.1:4222`

### 3. **telegram-gateway** (Python FastAPI)
- Міст між Telegram Bot API і NATS
- Базовий FastAPI сервіс з `/healthz` endpoint
- Буде розширений через Cursor для:
  - Читання апдейтів з Telegram
  - Публікації подій у NATS
  - Прийому HTTP команд від інших сервісів

## 📋 Передумови

- Docker + Docker Compose
- Telegram API credentials (API ID, API Hash) з https://my.telegram.org/apps
- Домен, що вказує на ваш сервер (опціонально для майбутнього HTTPS)

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

### 1. Налаштування змінних середовища

Створіть `.env` файл у кореневій директорії:

```bash
cp .env.example .env
```

Заповніть `.env` вашими значеннями:

```env
TELEGRAM_API_ID=YOUR_API_ID
TELEGRAM_API_HASH=YOUR_API_HASH
GATEWAY_DOMAIN=gateway.daarion.city
```

### 2. Запуск стеку

```bash
docker compose up -d
```

### 3. Перевірка статусу

Перевірте, що всі контейнери запущені:

```bash
docker compose ps
```

Очікуваний вивід:
```
NAME                 STATUS    PORTS
telegram-bot-api     running   127.0.0.1:8081->8081/tcp
nats                 running   127.0.0.1:4222->4222/tcp
telegram-gateway     running   127.0.0.1:8000->8000/tcp
```

## 🧪 Тестування

### 1. Перевірка telegram-gateway

```bash
curl http://127.0.0.1:8000/healthz
```

Очікувана відповідь:
```json
{
  "status": "ok",
  "service": "telegram-gateway",
  "telegram_api": "http://telegram-bot-api:8081",
  "nats": "nats://nats:4222"
}
```

### 2. Перевірка Local Telegram Bot API

Замініть `<YOUR_BOT_TOKEN>` на ваш реальний токен бота:

```bash
curl http://127.0.0.1:8081/bot<YOUR_BOT_TOKEN>/getMe
```

Очікувана відповідь (JSON з інформацією про бота):
```json
{
  "ok": true,
  "result": {
    "id": 123456789,
    "is_bot": true,
    "first_name": "YourBot",
    "username": "your_bot"
  }
}
```

### 3. Перевірка NATS

```bash
docker logs nats
```

Має показувати успішний запуск NATS сервера.

## 📁 Структура проєкту

```
telegram-infrastructure/
├── docker-compose.yml          # Конфігурація Docker Compose
├── .env                        # Змінні середовища (не в git)
├── .env.example               # Приклад змінних
├── README.md                   # Ця документація
├── data/                       # Дані (автоматично створюється)
│   └── telegram-bot-api/      # Дані Local Telegram Bot API
└── telegram-gateway/           # Telegram Gateway сервіс
    ├── Dockerfile
    ├── requirements.txt
    └── app/
        ├── __init__.py
        └── main.py            # FastAPI додаток
```

## 🔒 Безпека

- **telegram-bot-api** доступний тільки на localhost (`127.0.0.1:8081`)
- **nats** доступний тільки на localhost (`127.0.0.1:4222`)
- **telegram-gateway** доступний тільки на localhost (`127.0.0.1:8000`)
- Для публічного доступу додайте reverse proxy (Caddy/Traefik/nginx) з HTTPS

## 🔄 Управління

### Зупинка сервісів

```bash
docker compose down
```

### Перезапуск сервісу

```bash
docker compose restart telegram-gateway
```

### Перегляд логів

```bash
# Всі сервіси
docker compose logs -f

# Конкретний сервіс
docker compose logs -f telegram-gateway
```

### Rebuild після змін коду

```bash
docker compose up -d --build telegram-gateway
```

## 📝 Наступні кроки

Після того, як інфраструктура запрацює, використовуйте **Cursor** для розробки логіки `telegram-gateway`:

1. **Інтеграція aiogram** — для роботи з Telegram Bot API
2. **NATS publisher** — публікація подій у NATS
3. **Webhook endpoints** — прийом команд від інших сервісів
4. **Message routing** — маршрутизація повідомлень між агентами

## 🐛 Troubleshooting

### Контейнери не запускаються

```bash
docker compose logs telegram-bot-api
```

### Порти зайняті

Переконайтесь, що порти 8081, 4222, 8000 вільні:

```bash
lsof -i :8081
lsof -i :4222
lsof -i :8000
```

### Проблеми з правами доступу

```bash
chmod -R 755 data/
```

## 📚 Посилання

- [Local Telegram Bot API](https://github.com/tdlib/telegram-bot-api)
- [NATS](https://nats.io/)
- [FastAPI](https://fastapi.tiangolo.com/)
- [aiogram](https://docs.aiogram.dev/) (для майбутньої інтеграції)