# Архитектура проекта

## Технологический стек

### Mobile (iOS / Android)
- **Фреймворк**: React Native 0.76+ (или Flutter — уточнить перед стартом)
- **Навигация**: React Navigation 7 (bottom tabs + stack)
- **Стейт-менеджмент**: Zustand + React Query (TanStack Query)
- **UI-библиотека**: кастомная дизайн-система (см. `design-system.md`)
- **Push-уведомления**: Firebase Cloud Messaging (Android) + APNs (iOS)
- **Формы**: React Hook Form + Zod валидация
- **Хранение**: AsyncStorage (настройки), Keychain/Keystore (токены)
- **SIP/VoIP**: react-native-location / JsSIP (SIP/2.0, RTP/SRTP, SRTP/TLS)
- **Фоновые звонки**: PushKit VoIP (iOS) + Foreground Service (Android)

### Backend API
- **Язык**: Node.js 22 LTS / TypeScript 5.5+
- **Фреймворк**: NestJS 11
- **ORM**: Prisma 6
- **БД**: PostgreSQL 17
- **Кэш**: Redis 8
- **Аутентификация**: JWT (access 15 мин + refresh 30 дней), авторизация по телефону + пароль; API-ключи для серверных интеграций
- **API-стиль**: REST (OpenAPI 3.1 спецификация), cursor-based пагинация
- **Rate limiting**: 1000 запросов/мин (настраивается на уровне API-ключа)
- **Очереди задач**: BullMQ (уведомления, синхронизация с 1С, webhooks, email-рассылки)
- **Хранение файлов**: S3-совместимое хранилище (аватары, отчёты, логотипы)
- **Webhooks**: исходящие события с HMAC-SHA256 подписью, retry (3 попытки, экспоненциальная задержка)
- **Multi-tenancy**: Row-Level Security (RLS) в PostgreSQL + TenantResolver middleware (v1), с абстракцией DataSourceProvider для миграции на DB-per-tenant / K8s-namespace
- **Модульность**: Feature flags через таблицу `club_modules` + NestJS Guard `@RequireModule('sip')` + usage metering через BullMQ
- **Billing / Metering**: UsageMeterService — подсчёт использования ресурсов (пользователи, клиенты, звонки, webhooks, push), cron-агрегация, проверка лимитов

### Web Admin Panel (Рецепция + Аналитика)
- **Фреймворк**: Next.js 15 (App Router)
- **UI**: shadcn/ui + Tailwind CSS 4
- **Таблицы**: TanStack Table
- **Графики**: Recharts
- **Формы**: React Hook Form + Zod

### Web Club Admin Panel (Админка клуба)
- **Фреймворк**: Next.js 15 (App Router), отдельное приложение или раздел в web-admin
- **UI**: shadcn/ui + Tailwind CSS 4
- **Навигация**: боковое меню (10 разделов: дашборд, сотрудники, департаменты, залы, каталог услуг, уведомления, интеграции, email-рассылки, лицензия, настройки)

### Web Platform Admin Panel (Суперадминистратор)
- **Фреймворк**: Next.js 15 (App Router), отдельный URL (admin.{domain})
- **UI**: shadcn/ui + Tailwind CSS 4
- **Безопасность**: 2FA (TOTP) обязательна, IP-whitelisting опционально, audit log

### Инфраструктура
- **Контейнеризация**: Docker + Docker Compose
- **Оркестрация**: Kubernetes (production) / Docker Compose (dev/staging)
- **CI/CD**: GitHub Actions
- **Мониторинг**: Prometheus + Grafana
- **Логирование**: Loki + Promtail
- **Reverse proxy**: Traefik / Nginx
- **SIP-инфраструктура**: STUN/TURN/ICE сервер для NAT traversal

### Интеграции
- **1С:Фитнес клуб**: двусторонняя синхронизация (REST/SOAP API)
- **SIP-телефония**: встроенный SIP-клиент (SIP/2.0 RFC 3261, G.711 + Opus, SRTP)
- **Мессенджеры**: WhatsApp Business API / Telegram Bot API
- **Email-рассылки**: транзакционные и маркетинговые письма (SMTP / SendGrid / Mailgun / Unisender)
- **Webhooks**: 15 типов исходящих событий для внешних интеграций

## Структура монорепо

```
fitcrm/
├── apps/
│   ├── mobile/                    # React Native приложение
│   │   ├── src/
│   │   │   ├── app/               # Точка входа, навигация
│   │   │   ├── screens/           # Экраны по разделам
│   │   │   │   ├── auth/          # Авторизация (1.1)
│   │   │   │   ├── home/          # Главная: статистика, занятия, рейтинг, долги (1.2–1.7)
│   │   │   │   ├── schedule/      # Расписание: календарь, создание тренировок (4.1–4.8)
│   │   │   │   ├── clients/       # Клиенты: список, карточка, цели/травмы (5.1–5.2)
│   │   │   │   ├── funnel/        # Воронка: новые, назначенные, проведённые (6.1–6.7)
│   │   │   │   ├── stats/         # Статистика: воронка конверсии, отчёты (2.1–2.5)
│   │   │   │   ├── rating/        # Рейтинг тренеров (3.1–3.2)
│   │   │   │   ├── coordinator/   # Координатор: распределение, статистика (8.1–8.4)
│   │   │   │   ├── sales/         # Выставление продаж (7.2)
│   │   │   │   ├── work-schedule/ # График работы (7.3)
│   │   │   │   ├── sleeping/      # Спящие клиенты (7.4)
│   │   │   │   ├── sip/           # SIP-клиент: экран звонка, журнал (12.1–12.4)
│   │   │   │   └── notifications/ # Уведомления (10.1–10.3)
│   │   │   ├── components/        # Переиспользуемые UI-компоненты
│   │   │   ├── services/          # API-клиенты, push-сервис, SIP-сервис
│   │   │   ├── stores/            # Zustand stores (auth, clients, schedule, sip...)
│   │   │   ├── hooks/             # Кастомные хуки (useSIPCall, useCallLog...)
│   │   │   ├── types/             # TypeScript типы и интерфейсы
│   │   │   ├── utils/             # Хелперы, форматирование, валидация
│   │   │   └── theme/             # Дизайн-токены, цвета, типография
│   │   └── package.json
│   ├── web-admin/                 # Next.js веб-панель (рецепция + аналитика)
│   ├── web-club-admin/            # Next.js панель администратора клуба (15.1–15.10)
│   ├── web-platform-admin/        # Next.js панель суперадминистратора (14.1–14.6)
│   └── api/                       # NestJS backend
│       ├── src/
│       │   ├── modules/           # auth, users, clients, schedule, funnel, sales, stats,
│       │   │                      # rating, notifications, reports, work-schedule, sip,
│       │   │                      # webhooks, clubs, licenses, modules, metering,
│       │   │                      # provisioning, catalog, departments, rooms,
│       │   │                      # integration, email, themes
│       │   ├── common/            # Guards, interceptors, decorators, pipes
│       │   ├── config/            # Конфигурация, env-переменные, multi-tenancy
│       │   └── prisma/            # Схема БД, миграции, seed
│       └── package.json
├── packages/
│   ├── shared-types/              # Общие TypeScript типы (mobile + web + api)
│   ├── api-client/                # Сгенерированный API-клиент из OpenAPI
│   └── validators/                # Общие Zod-схемы валидации
├── infra/                         # Docker, k8s, STUN/TURN, GitHub Actions
├── docs/                          # ТЗ, план, OpenAPI, webhooks, диаграммы
├── CLAUDE.md                      # Компактные инструкции + ссылки на .claude/docs/
├── package.json                   # Monorepo root (pnpm workspaces)
├── pnpm-workspace.yaml
└── turbo.json                     # Turborepo конфигурация
```
