diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 0000000..17fdf22
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,226 @@
+# Архитектура XLX Server
+
+## 1. Назначение
+
+XLX Server — это управляемая платформа для DMR-пользователей, построенная вокруг XLX reflector и собственной системы регистрации, оплаты, проверки позывных и контроля доступа.
+
+Главная идея: пользователь не просто подключается к открытому XLX, а проходит понятный жизненный цикл:
+
+1. регистрация;
+2. проверка позывного;
+3. оплата;
+4. получение ID и пароля;
+5. подключение Pi-Star;
+6. продление доступа или блокировка после окончания тарифа.
+
+## 2. Основные компоненты
+
+### 2.1 XLX Core
+
+Отвечает за работу самого рефлектора.
+
+Задачи:
+
+- установка XLX reflector;
+- управление системным сервисом;
+- хранение конфигурации;
+- контроль модулей;
+- перезапуск после изменения настроек;
+- сбор статуса.
+
+### 2.2 Web Panel
+
+Личный кабинет пользователя и админка.
+
+Пользовательские функции:
+
+- регистрация по позывному;
+- вход в кабинет;
+- статус проверки;
+- статус оплаты;
+- данные для подключения Pi-Star;
+- срок действия доступа;
+- история оплат;
+- инструкция подключения.
+
+Админские функции:
+
+- список пользователей;
+- ручная проверка/блокировка;
+- ручное продление доступа;
+- управление тарифами;
+- просмотр оплат;
+- просмотр логов подключений;
+- управление ID-диапазонами;
+- настройки сервера.
+
+### 2.3 Callsign Verifier
+
+Модуль проверки позывного по внешним источникам.
+
+MVP-логика:
+
+- пользователь вводит позывной;
+- система нормализует его в верхний регистр;
+- проверяет формат;
+- делает запрос к настроенной базе;
+- сохраняет результат проверки;
+- при ошибке отправляет заявку в ручную модерацию.
+
+Важно: внешний источник проверки должен быть заменяемым адаптером, чтобы не прибивать проект гвоздями к одной базе.
+
+### 2.4 ID Allocator
+
+Модуль выдачи внутренних ID.
+
+Требования:
+
+- ID уникален;
+- ID закрепляется за пользователем;
+- диапазон ID задаётся в настройках;
+- повторная регистрация того же позывного не создаёт новый ID;
+- заблокированный пользователь не освобождает ID автоматически;
+- ручное переназначение возможно только админом.
+
+### 2.5 Billing
+
+Модуль платной регистрации и продления.
+
+MVP:
+
+- тарифы;
+- ручное подтверждение оплаты;
+- дата окончания доступа;
+- блокировка после окончания срока.
+
+Дальше:
+
+- YooKassa;
+- ЮMoney;
+- СБП/карта через ручное подтверждение;
+- webhooks оплат;
+- счета/чеки при необходимости.
+
+### 2.6 Access Gateway
+
+Слой контроля доступа к серверу.
+
+Задачи:
+
+- хранить пароль пользователя;
+- проверять активность подписки;
+- формировать allowlist/auth-файл для XLX/DMR-шлюза;
+- применять изменения без ручного редактирования конфигов;
+- логировать попытки подключения.
+
+На первом этапе допускается генерация конфигурационных файлов и перезапуск сервиса. Позже можно вынести это в отдельный daemon.
+
+### 2.7 Installer/Updater
+
+Обязательный компонент, чтобы проект нормально ставился на чистый сервер.
+
+Функции:
+
+- установка системных пакетов;
+- установка зависимостей;
+- настройка Nginx;
+- настройка PHP/Python runtime;
+- создание БД;
+- миграции;
+- установка systemd-сервисов;
+- выпуск/подготовка SSL;
+- бэкап перед обновлением;
+- откат при ошибке.
+
+## 3. Роли
+
+### User
+
+- регистрируется;
+- оплачивает;
+- получает данные подключения;
+- видит статус доступа.
+
+### Moderator
+
+- проверяет спорные позывные;
+- подтверждает ручные оплаты;
+- блокирует пользователей.
+
+### Admin
+
+- управляет системой полностью;
+- меняет настройки сервера;
+- управляет тарифами;
+- управляет ID-диапазонами;
+- запускает обновления.
+
+## 4. Жизненный цикл пользователя
+
+```text
+new -> callsign_pending -> callsign_verified -> payment_pending -> active -> expired
+                                      |              |
+                                      v              v
+                                  rejected        blocked
+```
+
+## 5. Подключение Pi-Star
+
+Пользователь получает в кабинете:
+
+- адрес сервера;
+- порт;
+- позывной/логин;
+- пароль;
+- ID;
+- модуль по умолчанию;
+- готовую инструкцию.
+
+## 6. База данных
+
+Минимальные сущности:
+
+- users;
+- callsign_checks;
+- dmr_ids;
+- tariffs;
+- payments;
+- access_credentials;
+- server_settings;
+- connection_logs;
+- audit_logs.
+
+## 7. Безопасность
+
+- пароли хранить только в виде хэша;
+- пароль для подключения генерировать отдельно от пароля кабинета;
+- админские действия писать в audit log;
+- закрыть прямой доступ к служебным файлам;
+- не хранить платёжные данные карт;
+- все webhooks проверять по подписи.
+
+## 8. Дорожная логика версий
+
+### v0.1.x
+
+Каркас, документация, установщик, БД, базовая панель.
+
+### v0.2.x
+
+Регистрация, пользователи, проверка позывных, выдача ID.
+
+### v0.3.x
+
+Оплаты, тарифы, ручное подтверждение, срок доступа.
+
+### v0.4.x
+
+Генерация доступа для Pi-Star и управление auth/allowlist.
+
+### v0.5.x
+
+Интеграция с XLX reflector и статус сервера.
+
+### v1.0.0
+
+Готовый продукт: установка, админка, кабинет, оплата, доступ, мониторинг и обновления.