LOTTY A/B Platform

A/B-платформа для продуктовых экспериментов. Позволяет запускать эксперименты на feature flags, отслеживать метрики, автоматически останавливать деградирующие варианты и принимать решения на данных.

Автор: Вадим Христенко

Проект создан с любовью и небольшим юмором (Спасибо Астольфо за вдохновение и стиль!). ШаховПобеда и БалюкПобеда, молодцы - всё заработает, всё будет хорошо, на защиту приду уверенно. Код скомпилирован, тесты пройдены (72 E2E check ✓), Telegram работает, learnings протестирован. Ничего не сломалось (вроде).

Стек

Как это работает

Платформа решает три задачи:

1. Выдача решений (POST /decide). Продукт спрашивает: «что показать пользователю user-42 для флага button_color?». Платформа проверяет эксперименты, применяет таргетинг DSL, детерминированно выбирает вариант через xxHash3 и возвращает значение + decision_id.

2. Сбор событий (POST /events, POST /events/batch). Продукт сообщает: «user-42 кликнул кнопку». События привязываются к decision_id, проходят валидацию по каталогу типов, дедупликацию и атрибуцию.

3. Автоматическая реакция. Фоновый guardrail-чекер каждые N секунд пересчитывает метрики из каталога. Если порог превышен, эксперимент ставится на паузу или откатывается к контролю.

Ключевые идеи

Детерминизм через хеширование. Один и тот же пользователь всегда попадает в один вариант. Для бакетинга используется xxh3_64(user_id:experiment_id), для выбора варианта xxh3_64(user_id:experiment_id:variant). Никакого дополнительного хранилища для sticky-сессий не нужно.

Каталоги, а не хардкод. Типы событий и метрики задаются в каталогах через API. Guardrail-ы привязываются к метрикам из каталога. Новые типы событий и метрики добавляются без правки кода.

Fire-and-forget на hot path. Запись решений и участия в /decide выполняется через tokio::spawn без ожидания. Счётчик участия кэшируется в Valkey с TTL 60с. Цель: минимальная латенция на 100k RPS.

DSL-таргетинг. Собственный лексер и парсер: age >= 18 AND country IN ("RU", "KZ"). Поддерживает AND/OR/NOT, сравнения, множества IN/NOT IN, вложенные скобки. Если атрибут отсутствует, условие считается false.

Уведомления (C7). Telegram, Discord, Slack. Каждая команда заводит свой канал с bot_token. Правила уведомлений настраиваются через API: какие события куда слать.

Learnings Library (C9). После завершения эксперимента сохраняется structured learning: гипотеза, результат, impact, теги. Поиск по похожим экспериментам через tags, flag_key, free-text.

Insights (C8). Аналитика качества данных: доля отклонённых событий, traffic skew, полнота атрибуции, сводка платформы.

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

docker compose up -d
# Ждём готовности (~30 секунд)
curl http://localhost:80/ready

Подробная инструкция: docs/RUNBOOK.md

Swagger UI / OpenAPI

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

• Swagger UI: http://localhost:80/docs/ - Astolfo Edition с кастомной темой
• OpenAPI JSON: http://localhost:80/api-docs/openapi.json

Документация генерируется автоматически из кода через utoipa 5.4. Все 62 API-эндпоинта аннотированы с описаниями на русском. Swagger UI встроен прямо в бинарник через rust-embed - никаких внешних файлов или CDN.

Примечание: НЕ используется utoipa-swagger-ui - этот крейт загружает ассеты по сети при сборке, что ломает Docker Buildx в сетевой изоляции. Вместо него Swagger UI dist-файлы лежат в swagger-ui/ и компилируются в бинарник.

API

Публичные (без токена)

Аутентификация (rate limited)

Защищённые (Bearer token)

Роли

Жизненный цикл эксперимента

draft -> review -> approved -> launched -> paused -> completed -> archived

На любом шаге возможен reject (возврат в draft для доработки). Guardrail может автоматически поставить на паузу или откатить к контролю.

Тесты

cargo test

81 тест (61 unit + 20 inline). Интеграционные: bash scripts/integration_tests.sh.

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