commit 5b682894baa839b8a02373a437ed75bbc6573cb0
Author: Andrewkydev <grusha.belaev@gmail.com>
Date:   Sun Feb 22 19:30:40 2026 +0300

    first commit

diff --git a/01-system-overview.md b/01-system-overview.md
new file mode 100644
index 0000000..b353cf0
--- /dev/null
+++ b/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`) применяются для глобальных прав (например, модерация каталога).
diff --git a/02-processes-and-services.md b/02-processes-and-services.md
new file mode 100644
index 0000000..0cd165b
--- /dev/null
+++ b/02-processes-and-services.md
@@ -0,0 +1,50 @@
+# Processes And Services
+
+## Точка входа
+
+`cmd/app/main.go` -> `bootstrap.RunApp()`
+
+## Что запускает `RunApp`
+
+1. загрузку `.env`;
+2. startup guard (в prod);
+3. загрузку локалей;
+4. подключение к PostgreSQL;
+5. миграции;
+6. запуск API-сервера;
+7. запуск VK-бота;
+8. автозапуск внутренних сервисов (опционально).
+
+## Основные процессы
+
+1. `api`  
+   Основной HTTP API приложения.
+2. `bot`  
+   Longpoll/командный runtime VK-бота.
+3. `whois-service`  
+   Отдельный HTTP-сервис whois/rdap.
+4. `addons-v8-service`  
+   Сервис изолированного исполнения аддонов (V8 runtime).
+
+## Автостарт дополнительных сервисов
+
+Переменные:
+
+1. `AUTOSTART_WHOIS_SERVICE` (по умолчанию `true`);
+2. `AUTOSTART_ADDONS_V8_SERVICE` (по умолчанию `true`).
+
+## Связанные cmd-пакеты
+
+1. `cmd/api` — отдельный запуск API (если нужен отдельно).
+2. `cmd/bot` — отдельный запуск бота.
+3. `cmd/miniapp-receiver` — сервисный контур для miniapp/webhook.
+4. `cmd/whois-service` — standalone whois service.
+5. `cmd/addons-v8-service` — standalone addons runtime service.
+
+## Graceful shutdown
+
+При `SIGINT/SIGTERM`:
+
+1. останавливается bot loop;
+2. вызывается `Shutdown` у API;
+3. вызывается `Shutdown` у `whois-service` и `addons-v8-service` (если запущены).
diff --git a/03-bot-commands.md b/03-bot-commands.md
new file mode 100644
index 0000000..314cc92
--- /dev/null
+++ b/03-bot-commands.md
@@ -0,0 +1,156 @@
+# Bot Commands
+
+Ниже команды по модулям. Описания — на уровне назначения, без внутренней логики.
+
+## Общая регистрация команд
+
+Команды подключаются в `internal/bootstrap/bot_commands.go`.
+
+Основные командные модули:
+
+1. `chatmanager`
+2. `addons`
+3. `utils`
+4. `games`
+5. `query` (minecraft)
+6. `whois`
+7. `screen`
+
+## 1) Addons module
+
+Команды:
+
+1. `/addon` (управление аддоном, подкоманды)
+2. `/addons` (список аддонов чата)
+
+Подкоманды `/addon`:
+
+1. `role` — смена роли/приоритета доступа к аддону.
+2. `prefix` — префикс вызова аддонов.
+3. `sandbox` — статус/вкл/выкл/движок sandbox.
+4. `install` — установка аддона из каталога.
+5. `enable|disable` — вкл/выкл аддон.
+6. `delete` — удалить аддон.
+7. `<name> <code>` — создание аддона.
+
+Отдельно:
+
+1. unknown command handler перехватывает префиксные вызовы аддонов.
+
+## 2) Chatmanager module
+
+### 2.1 Moderation
+
+1. `kick`, `multikick`, `kickbots`, `kickdogs`
+2. `kickafter`, `kickfrom`, `kickmessages`
+3. `inactive`, `kickinactive`, `kickleft`
+4. `ban`, `multiban`, `everban`, `multieverban`, `unban`
+5. `mute`, `unmute`
+6. `warn`, `unwarn`, `warnlist`, `banlist`
+7. `selfban`
+
+### 2.2 Roles
+
+1. `role`, `promote`, `demote`
+2. `joinrole`
+3. `hierarchy`, `tree`, `staff`, `roles`
+4. `createrole`, `deleterole`, `rolerename`, `roleemoji`
+5. fixed helpers: `membercmd`, `helpercmd`, `modcmd`, `hmodcmd`, `admincmd`, `clearcmd`, `unrole`
+
+### 2.3 Access / Permissions
+
+1. `immunity`, `unimmunity`, `immunities`
+2. `perm`, `perms`
+
+### 2.4 Settings
+
+1. `prefix`, `timezone`
+2. `quieterrors`, `quieterrorsru`
+3. `language`, `chatlang`
+4. `autounban`
+5. `warnlimit`, `limitwarns`
+6. `warntime`, `warnlifetime`
+7. `kickrole`, `inviterole`, `titlerole`, `pinrole`, `adminrole`
+8. `kickmenu`, `inactivejoin`, `autodelete`
+9. `statstype`, `catalog`, `news`, `whitelist`, `chattype`
+
+### 2.5 Service / Runtime / Help
+
+1. `logs`, `chathelp`
+2. `resync`
+3. `rules`, `setrules`
+4. `motd`, `setmotd`
+5. `online`, `offline`, `status`, `chatinfo`
+6. `announce`
+7. notification toggles: `notifybans`, `notifyunbans`, `notifywarns`, `notifyprevents`, `notifyevents`, `togglegroup`, `subscription`
+8. `backlog`, `actions`, `captcha`, `write`, `cleanup`
+
+### 2.6 Automation
+
+1. Limits: `limits`, `limit`, `removelimit`
+2. Timers: `timers`, `timer`, `remtask`
+3. Events/Prevents: `events`, `addevent`, `redevent`, `remrule`, `preevents`, `prevent`, `remprevent`
+
+### 2.7 Stats & Templates
+
+1. `chatstats`, `stata`, `topstats`, `statlist`
+2. `setwarn`, `setmute`
+
+### 2.8 Anywhere commands (доступ вне чата)
+
+1. `helpanywhere` / `helpme`
+2. `mychats`, `rating`
+3. `hidekeyboard`
+4. `report`
+5. `bind`, `tochat`
+6. `donotnotify`, `nomention`
+
+### 2.9 Callback commands
+
+1. `callback`
+2. `callbacktest`
+3. `callbacksecret`
+
+## 3) Utils module
+
+1. `color` / `colour`
+2. `gradient` / `grad`
+3. `currency` / `rates` / `convert`
+4. `datereg` / `regdate`
+5. `ip` / `hostip` / `dns`
+6. `ping` / `latency`
+7. `password` / `pass` / `pwd`
+8. `phar` / `zip` / `convertation` / `pluginconvert`
+
+Примечание:
+
+1. команда `jar` есть в коде как отключенный блок.
+
+## 4) Games module
+
+1. `balance` / `coins` / `wallet`
+2. `bonus` / `reward`
+3. `coin` / `coinflip`
+4. `transfer` / `pay`
+
+## 5) Query module (Minecraft)
+
+1. `mcpe` / `mcbe` / `bedrock`
+2. `java` / `mcjava` / `mcpc`
+3. `query` / `q` (обертка-подсказка)
+
+Поддерживаются callback-кнопки refresh для обновления статуса.
+
+## 6) Whois module
+
+1. `whois`
+2. aliases: `ip`, `ipinfo`
+
+Возвращает сводку по IP/домену через whois/rdap-клиент.
+
+## 7) Screen module
+
+1. `screen` / `screenshot` / `shot`
+2. admin: `screen_admin` / `screenctl`
+
+`screen` — скриншот URL; `screen_admin` — управление доступностью/блоклистом.
diff --git a/04-manager-api.md b/04-manager-api.md
new file mode 100644
index 0000000..eff9b95
--- /dev/null
+++ b/04-manager-api.md
@@ -0,0 +1,79 @@
+# Manager API
+
+Источник маршрутов: `internal/modules/manager/http/module.go`.
+
+## Public
+
+1. `POST /tenant/vk/callback/{path_token}/{tenant_id}/{group_id}`  
+   Callback endpoint для tenant/group.
+2. `OPTIONS /tenant/vk/callback/{path_token}/{tenant_id}/{group_id}`  
+   CORS/preflight.
+
+## Private (`/manager/*`)
+
+### Me
+
+1. `GET /manager/me/profile` — профиль менеджера (`account_type`, `account_code`).
+2. `GET /manager/me/settings` — пользовательские настройки.
+3. `PUT /manager/me/settings` — обновление пользовательских настроек.
+
+### Chats / Workspace
+
+1. `GET /manager/chats` — список доступных чатов.
+2. `GET /manager/chats/workspace/{chat_uid}` — агрегированный workspace чата.
+3. `POST /manager/chats/workspace/{chat_uid}/events` — создать event rule.
+4. `POST /manager/chats/workspace/{chat_uid}/timers` — создать timer.
+5. `GET /manager/chats/workspace/{chat_uid}/actions` — список audit-действий.
+6. `GET /manager/chats/workspace/{chat_uid}/stats` — статистика чата.
+
+### Chat addons
+
+1. `GET /manager/chats/{peer_id}/addons` — список аддонов чата.
+2. `POST /manager/chats/{peer_id}/addons` — создать аддон в чате.
+3. `PATCH /manager/chats/{peer_id}/addons/{name}` — изменить аддон.
+4. `DELETE /manager/chats/{peer_id}/addons/{name}` — удалить аддон.
+5. `POST /manager/chats/{peer_id}/addons/install` — установить аддон из каталога.
+
+### Chat settings
+
+1. `GET /manager/chats/{peer_id}/settings` — получить базовые настройки.
+2. `PUT /manager/chats/{peer_id}/settings` — обновить базовые настройки.
+
+### Groups / Callback
+
+1. `GET /manager/groups` — группы пользователя.
+2. `POST /manager/groups/connect` — подключить группу.
+3. `GET /manager/groups/{group_id}/settings` — настройки группы.
+4. `PUT /manager/groups/{group_id}/settings` — обновить настройки группы.
+5. `POST /manager/groups/{group_id}/token` — сохранить token.
+6. `POST /manager/groups/{group_id}/callback/rotate-secret` — ротация секрета.
+7. `GET /manager/groups/{group_id}/callback/verify` — верификация callback.
+8. `GET /manager/groups/{group_id}/callback/events` — лог callback событий.
+9. `POST /manager/groups/{group_id}/callback/ping` — тест callback.
+10. `GET /manager/groups/{group_id}/status` — статус callback-конфигурации.
+
+### Addons catalog
+
+1. `GET /manager/addons/catalog` — публичный каталог approved аддонов.
+2. `GET /manager/addons/catalog/categories` — список стандартизированных категорий.
+3. `GET /manager/addons/catalog/{addon_id}/versions` — история версий каталожного аддона.
+4. `POST /manager/addons/catalog` — создать draft в каталоге.
+5. `GET /manager/addons/catalog/mine` — мои каталогные аддоны.
+6. `POST /manager/addons/catalog/{addon_id}/submit` — отправить на модерацию.
+7. `GET /manager/addons/moderation/pending` — pending для модерации.
+8. `POST /manager/addons/moderation/{addon_id}/decision` — решение модерации.
+
+## Каталог аддонов: важные поля
+
+1. `title`, `slug`, `addon_name`
+2. `category` (стандартизированная)
+3. `image_url`
+4. `usage_example`
+5. `gallery` (массив URL)
+6. `description`
+7. `code`
+
+## Доступы
+
+1. Модерация каталога (`pending`, `decision`) ограничена глобальным уровнем аккаунта `account_type >= moderator`.
+2. Дополнительно поддерживается legacy-список moderator VK IDs.
diff --git a/05-data-model-notes.md b/05-data-model-notes.md
new file mode 100644
index 0000000..c947bef
--- /dev/null
+++ b/05-data-model-notes.md
@@ -0,0 +1,80 @@
+# Data Model Notes
+
+Это краткая карта ключевых сущностей. Полный состав — в `internal/domain/*`.
+
+## Пользователь и менеджер
+
+1. `users` (`domain.User`)  
+   Базовый профиль пользователя, язык, ник, игровые поля.
+2. `manager_accounts` (`domain.ManagerAccount`)  
+   Связка user <-> manager, enabled, глобальный `account_type`.
+3. `manager_user_settings` (`domain.ManagerUserSetting`)  
+   Персональные настройки для miniapp.
+
+## Группы и callback
+
+1. `manager_groups` (`domain.ManagerGroup`)  
+   Привязанные VK группы.
+2. `manager_group_tokens` (`domain.ManagerGroupToken`)  
+   Токены групп (зашифрованные).
+3. `manager_callback_endpoints` (`domain.ManagerCallbackEndpoint`)  
+   Параметры callback endpoint.
+4. `manager_callback_events` (`domain.ManagerCallbackEvent`)  
+   Лог входящих callback событий.
+5. `manager_group_settings` (`domain.ManagerGroupSetting`)  
+   Настройки групп в key/value.
+
+## Чаты и чат-менеджер
+
+1. `chats` (`domain.Chat`)  
+   Чаты, `peer_id`, `chat_uid`.
+2. `chat_settings` (`domain.ChatSetting`)  
+   Основные настройки чата.
+3. `chat_members`, `member_roles`, `roles`  
+   Участники и RBAC.
+4. `permission_roles`, `permission_users`  
+   Права команд.
+5. `sanctions`, `immunities`  
+   Бан/мут/пред/иммунитеты.
+6. `event_rules`, `prevent_rules`, `timer_tasks`  
+   Автоматизация.
+7. `audit_actions`, `command_logs`  
+   Журналы действий и команд.
+8. `statistics_message_daily`  
+   Агрегированная статистика.
+
+## Аддоны
+
+1. `chat_addons` (`domain.ChatAddon`)  
+   Установленные в чат аддоны.
+2. `chat_addon_db` / `chat_addon_shared_db`  
+   KV-хранилища для аддонов (локальное/shared).
+3. `chat_addon_invoke_logs`  
+   Логи вызовов аддонов.
+
+## Каталог аддонов
+
+1. `manager_addon_catalog` (`domain.ManagerAddonCatalog`)  
+   Карточка аддона каталога (метаданные, код, статус модерации).
+2. `manager_addon_catalog_versions` (`domain.ManagerAddonCatalogVersion`)  
+   Снимки версий.
+3. `manager_addon_moderation_logs` (`domain.ManagerAddonModerationLog`)  
+   Логи переходов статуса.
+4. `chat_addon_catalog_installs` (`domain.ChatAddonCatalogInstall`)  
+   Фиксация установок в чаты.
+
+## Account type (глобальный уровень)
+
+`manager_accounts.account_type`:
+
+1. `10` regular
+2. `20` enhanced
+3. `30` maximum
+4. `40` moderator
+5. `50` administrator
+6. `60` developer
+
+Применение:
+
+1. доступ к модерации каталога;
+2. staff-уведомления по аддонам (уровень `> 30`).
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8d134fa
--- /dev/null
+++ b/README.md
@@ -0,0 +1,25 @@
+# DuExpBot Technical Docs
+
+Этот каталог содержит техническую документацию по проекту без глубокого разбора бизнес-логики.
+
+## Состав
+
+1. `techdocs/01-system-overview.md`  
+   Что это за бот, ключевые подсистемы, общая архитектура.
+2. `techdocs/02-processes-and-services.md`  
+   Какие процессы запускаются, что делает каждый сервис.
+3. `techdocs/03-bot-commands.md`  
+   Команды бота по модулям (назначение, без внутренней логики).
+4. `techdocs/04-manager-api.md`  
+   HTTP API менеджера/miniapp: маршруты и смысл.
+5. `techdocs/05-data-model-notes.md`  
+   Основные сущности БД и их назначение.
+
+## Обновление
+
+Документация собрана по текущему коду репозитория и должна обновляться при:
+
+1. добавлении/удалении команд;
+2. изменении API;
+3. изменении состава процессов;
+4. изменении ключевых моделей БД.