docs: README — quick start, architecture, roles, deploy

README.md

@@ -0,0 +1,59 @@
+# IP WhiteList
+
+Self-service портал управления доверенными IPv4-адресами клиентов облачного провайдера.
+Записи исключаются из блокировки системами фильтрации во время DDoS-атак.
+
+**[Техническое задание](docs/ТЗ.md)** · **[Отчёт о соответствии ТЗ](docs/TZ-COMPLIANCE-REPORT.md)**
+
+## Быстрый старт
+
+```bash
+npm install
+cp .env.example .env   # заполнить переменные
+npm start              # http://localhost:3000
+npm test               # 104 API-теста
+npm run test:stress    # 191 стресс-тест
+```
+
+## Переменные окружения
+
+| Переменная | Назначение | По умолчанию |
+|---|---|---|
+| `DEV_MODE` | mock-аутентификация (`true` в dev, **запрещён** в prod) | — |
+| `ADMIN_CLIENT_ID` | clientId администратора | `WZ01112` |
+| `DEFAULT_LIMIT` | лимит записей на компанию | `15` |
+| `DATABASE_URL` | строка подключения PostgreSQL | — |
+| `SESSION_SECRET` | секрет сессий (**обязателен** в prod) | — |
+
+[Полный список в AGENT.md](AGENT.md#4-переменные-окружения)
+
+## Стек
+
+Node.js 18+ / Express 4 / EJS / PostgreSQL 17 / jsonwebtoken RS256
+
+## Архитектура
+
+```
+Browser → UI (EJS, сессия) → api-client → REST API (Bearer JWT) → PostgreSQL
+```
+
+Два слоя: SSR UI для браузера и JSON API для внешних потребителей.
+API — Bearer-only (без сессий), UI — сессия + Bearer-токен внутри.
+
+**[Подробная карта файлов в AGENT.md](AGENT.md#5-структура-файлов--карта-ответственности)**
+
+## Роли
+
+| Роль | clientId | Права |
+|---|---|---|
+| Клиент | Любой | CRUD своих записей в пределах лимита |
+| Администратор | `WZ01112` | CRUD всех записей, изменение лимитов, аудит |
+
+## Деплой
+
+Платформа: Nubes k8s. Редеплой — через Nubes UI из Gitea после `git push`.
+Production URL: `https://white.nodejsk8s.dev.nubes.ru`
+
+## Разработка
+
+Перед любой задачей читать [`AGENT.md`](AGENT.md) — полное руководство для агентов и разработчиков.