first commit

01-system-overview.md

@@ -0,0 +1,58 @@
+# System Overview
+
+## Назначение проекта
+
+`DuExpBot` — это платформа VK-бота и miniapp-панели для управления чатами и расширениями (аддонами).
+
+Основные направления:
+
+1. чат-менеджмент (модерация, роли, события, таймеры, статистика, правила);
+2. модульные команды и утилиты;
+3. каталог аддонов с модерацией и установкой в чаты;
+4. интеграции с внешними сервисами (whois/ip/minecraft-query/callback).
+
+## Технологический стек
+
+1. Backend: `Go`.
+2. База данных: `PostgreSQL`.
+3. ORM/миграции: `GORM` + `AutoMigrate`.
+4. VK API: `vksdk`.
+5. Miniapp frontend: `React + TypeScript + Vite`.
+6. Router HTTP: `gorilla/mux`.
+
+## Высокоуровневая архитектура
+
+1. `internal/bootstrap/*`  
+   Сборка и запуск приложения, wiring зависимостей.
+2. `internal/modules/*`  
+   Бизнес-модули (chatmanager, addons, manager API, callbacks и т.д.).
+3. `internal/modules/cmd/*`  
+   Командные модули бота.
+4. `internal/domain/*`  
+   Модели данных (ORM-сущности).
+5. `internal/db/*`  
+   Инициализация БД и миграции совместимости.
+6. `miniapp/*`  
+   UI-панель для управления.
+
+## Ключевые подсистемы
+
+1. `chatmanager`  
+   Управление поведением бота в чатах, RBAC, санкции, аудит, автоматизация.
+2. `addons`  
+   Чатовые аддоны, рантайм исполнения, каталогные установки.
+3. `manager`  
+   API для miniapp (чаты, группы, настройки, каталог, модерация).
+4. `callbacks`  
+   Webhook/callback-инфраструктура.
+5. `query`  
+   Запросы к игровым серверам (Minecraft), обновление статуса.
+6. `whois` + `whois-service`  
+   WHOIS/RDAP lookup контур.
+
+## Модель расширяемости
+
+1. Ботовые команды регистрируются модульно.
+2. Аддоны могут исполняться в sandbox/изолированном runtime.
+3. Каталог аддонов имеет этапы: draft -> pending -> approved/rejected/archived.
+4. Уровни аккаунта (`account_type`) применяются для глобальных прав (например, модерация каталога).