MailFrame API

Современная платформа для email-маркетинга, построенная на NestJS с поддержкой масштабных рассылок, аналитики и управления контактами.

🚀 Основные возможности

📧 Email Кампании

• Массовые рассылки с настраиваемой производительностью
• Планировщик кампаний с поддержкой отложенной отправки
• Система очередей на базе BullMQ для надежной доставки
• SMTP конфигурация с тонкой настройкой таймаутов и TLS
• Отслеживание доставки с классификацией ошибок (SOFT/HARD)

👥 Управление контактами

• Импорт/экспорт контактов (CSV, Excel)
• Дедупликация и слияние дубликатов
• Система тегов для сегментации
• Фильтры и поиск с сохранением настроек
• Engagement Score для оценки активности подписчиков

📊 Аналитика и отслеживание

• Отслеживание открытий и кликов
• HMAC подписи для защиты tracking ссылок
• Детальная аналитика кампаний
• Система метрик с Prometheus
• Логирование с Grafana и Loki

🎨 Шаблоны и блоки

• Редактор шаблонов с переиспользуемыми блоками
• Превью генерация с помощью Puppeteer
• Система тегов для организации шаблонов
• Responsive дизайн для всех устройств

🔐 Безопасность и аутентификация

• JWT токены с сессиями в Redis
• 2FA поддержка с QR кодами
• OAuth интеграция
• Система ролей и разрешений
• Безопасные подписи для tracking

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

• Backend: NestJS 11.0+, TypeScript 5.7+
• База данных: PostgreSQL 15+ с Prisma ORM
• Кэширование: Redis 7+
• Очереди: BullMQ для фоновых задач
• Мониторинг: Prometheus, Grafana, Loki
• Файлы: MinIO S3-совместимое хранилище
• Email: Nodemailer с SMTP
• Документация: Swagger/OpenAPI, ReDoc
• Контейнеризация: Docker, Docker Compose

📋 Системные требования

• Node.js 18+
• PostgreSQL 15+
• Redis 7+
• Docker & Docker Compose (рекомендуется)
• Минимум 2GB RAM
• 10GB свободного места

🚀 Быстрый старт

1. Клонирование репозитория

git clone <repository-url>
cd temply-api

2. Настройка окружения

cp .env.example .env
# Отредактируйте .env файл согласно вашим настройкам

3. Запуск с Docker (рекомендуется)

# Разработка
npm run docker:dev

# Остановка
npm run docker:stop

# Просмотр логов
npm run docker:logs

4. Ручная установка

# Установка зависимостей
npm install

# Генерация Prisma клиента
npx prisma generate

# Миграции базы данных
npx prisma migrate deploy

# Запуск в режиме разработки
npm run start:dev

🔧 Конфигурация

Переменные окружения

Основные настройки

# Приложение
APPLICATION_PORT=4200
APPLICATION_URL=http://localhost:4200
NODE_ENV=development

# База данных
POSTGRES_URI=postgresql://user:password@localhost:5432/temply

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# JWT
JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=7d

Настройки кампаний

# Производительность
CAMPAIGN_CONCURRENCY=10
CAMPAIGN_MESSAGE_RATE=10
CAMPAIGN_BATCH_SIZE=100

# Повторные попытки
CAMPAIGN_ATTEMPTS=5
CAMPAIGN_BACKOFF_TYPE=exponential
CAMPAIGN_BACKOFF_MS=5000

# SMTP
CAMPAIGN_SMTP_CONNECTION_TIMEOUT_MS=15000
CAMPAIGN_SMTP_DEBUG=false

Engagement система

# Веса событий
ENGAGEMENT_WEIGHT_SENT=1
ENGAGEMENT_WEIGHT_OPEN=5
ENGAGEMENT_WEIGHT_CLICK=10
ENGAGEMENT_WEIGHT_HARD_FAIL=-30
ENGAGEMENT_WEIGHT_UNSUB=-50

# Decay настройки
ENGAGEMENT_DECAY_ENABLED=true
ENGAGEMENT_DECAY_CRON=0 3 * * *
ENGAGEMENT_DECAY_PERCENT=5

HMAC tracking

TRACKING_HMAC_ENABLED=true
TRACKING_HMAC_SECRET=your-hmac-secret
TRACKING_HMAC_ALGO=sha256

Подробную конфигурацию смотрите в DOCS.md

📚 API Документация

После запуска приложения документация доступна по адресам:

• Swagger UI: http://localhost:4200/api/docs
• ReDoc: http://localhost:4200/api/redoc
• OpenAPI JSON: http://localhost:4200/api/swagger.json

📦 Сборка и деплой

Production сборка

npm run build
npm run start:prod

Docker production

npm run docker:prod

Структура проекта

src/
├── api/                    # API модули
│   ├── auth/              # Аутентификация
│   ├── campaigns/         # Кампании
│   ├── contacts/          # Контакты
│   ├── templates/         # Шаблоны
│   ├── analytics/         # Аналитика
│   └── ...
├── config/                # Конфигурация
├── core/                  # Ядро приложения
├── libs/                  # Общие библиотеки
│   ├── logging/           # Логирование
│   ├── database/          # База данных
│   ├── queue/             # Очереди
│   └── ...
├── app.module.ts          # Корневой модуль
└── main.ts               # Точка входа

database/
├── prisma/
│   ├── models/           # Модели данных
│   ├── migrations/       # Миграции
│   └── schema.prisma     # Схема

memory-bank/              # Документация проекта
├── tasks.md             # Активные задачи
├── progress.md          # Прогресс
└── archive/             # Архив задач

🔍 Мониторинг

Система включает полноценный стек мониторинга:

• Prometheus - Сбор метрик
• Grafana - Визуализация данных
• Loki - Агрегация логов
• Bull Board - Мониторинг очередей

Доступ к мониторингу:

• Grafana: http://localhost:3000
• Bull Board: http://localhost:4200/api/admin/queues

🤝 Разработка

Требования к коду

• ESLint для статического анализа
• Prettier для форматирования
• Husky для pre-commit хуков
• Conventional Commits

Команды для разработки

# Линтинг
npm run lint

# Форматирование
npm run format

# Отладка
npm run start:debug

# Перезапуск при изменениях
npm run start:dev