Sauron Frontend

Sauron Frontend — это веб-приложение для мониторинга цифровой активности вокруг продукта, бренда, сообщества или отдельного проекта. Оно собирает рабочие процессы в одном месте: здесь можно подключать источники данных, следить за упоминаниями, настраивать словари и правила алертов, а затем смотреть на общую картину через дашборды и аналитические метрики.

Приложение построено вокруг организаций и проектов. Организация задаёт рабочий контур команды, а проект становится самостоятельной единицей мониторинга со своими интеграциями, правилами, сигналами и аналитикой. Такой подход хорошо подходит для команд, которые одновременно ведут несколько продуктов, клиентов или сообществ.

Что умеет проект

• аутентифицировать пользователя и восстанавливать сессию между перезагрузками
• переключать активную организацию и сохранять текущий рабочий контекст
• создавать, редактировать и удалять проекты внутри организации
• открывать отдельное рабочее пространство проекта с разделами для упоминаний, аналитики, алертов, интеграций и словарей
• подключать внешние источники данных и управлять ими как интеграциями проекта
• собирать упоминания, фильтровать их по ключевым словам, тональности и качеству совпадения
• поддерживать whitelist, blacklist и списки критических слов
• задавать правила алертов по severity и пороговым значениям
• следить за трендами через дашборды и агрегированные показатели
• экспортировать данные по упоминаниям в CSV и Excel
• поддерживать локализацию интерфейса, переключение темы и встроенный онбординг
• использовать mock-аккаунты для локальной разработки и демо-сценариев

Доменные модели

Проект опирается на несколько понятных сущностей, вокруг которых строится весь продукт:

• Organization — верхний уровень рабочего пространства. Организация объединяет проекты, настройки и текущий контекст команды.
• Project — основная единица мониторинга. У проекта есть имя, описание, подключённые источники, правила алертов и собственная аналитика.
• Integration — канал поступления данных в проект. По сути это связь между мониторинговым контуром и внешней платформой, чатом, сайтом или другим источником.
• Integration source — конкретная внешняя точка, привязанная к интеграции: канал, URL, фид или иной источник контента.
• Post — единица собранного исходного контента.
• Mention — найденное совпадение внутри контента. Для упоминания важны ключевое слово, тональность и сила совпадения.
• Keyword list — проектный словарь, влияющий на интерпретацию сигналов. Сейчас продукт использует whitelist, blacklist и списки критических слов.
• Alert rule — правило, которое определяет, при каких условиях источник должен поднять значимый сигнал.
• Alert — операционное событие с severity и пороговым контекстом.
• Analytics — агрегированная модель состояния проекта: временные ряды, sentiment breakdown, счётчики алертов, activity score и другие производные показатели.
• User session — аутентифицированный пользователь и access token, через которые восстанавливается доступ к организациям и проектам.

Как устроен продукт

Интерфейс собран как единое рабочее пространство, а не как набор разрозненных страниц.

• Главная страница служит точкой входа в проекты текущей организации.
• Внутри проекта рабочие сценарии разделены по вкладкам: упоминания, обзорная аналитика, алерты, интеграции и словари.
• Отдельный раздел дашбордов показывает более общую картину по активности и тональности.
• Раздел настроек сосредоточен на контексте текущей организации.
• Онбординг помогает быстро пройти основной путь пользователя без отдельного изучения интерфейса.

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

• Vue 3 и TypeScript
• Vite для локальной разработки и продакшен-сборки
• Vue Router для маршрутизации
• Pinia для локального UI- и клиентского состояния
• Pinia Colada для серверного состояния, кеширования, загрузки и инвалидации
• OpenAPI-клиент, сгенерированный по спецификации, как единственный источник backend-контрактов
• Nuxt UI, Tailwind CSS 4 и сопутствующий UI-стек для интерфейса
• Vue I18n для локализации
• Zod для валидации и описания входных структур
• Storybook для изолированной разработки UI
• Vitest для unit-тестов
• Playwright для end-to-end сценариев
• Ultracite, Oxlint и Oxfmt для форматирования и статического контроля качества

Архитектура

Проект следует слоистой структуре в духе feature-sliced design. Идея простая: держать доменную логику рядом с доменом, маршрутную оркестрацию рядом со страницами, а общую инфраструктуру не смешивать с бизнес-частями.

• app — инициализация приложения, глобальные провайдеры, layouts и router
• pages — экраны, привязанные к маршрутам, и оркестрация на уровне страницы
• widgets — крупные UI-секции, которые собирают несколько features и entities
• features — переиспользуемые бизнес-взаимодействия и составная view-логика
• entities — доменные модели, API-обёртки, типы и маппинг данных
• shared — общая инфраструктура: сгенерированный API-клиент, базовые UI-блоки, конфиг, утилиты и технические зависимости

Для проекта особенно важны два архитектурных решения:

• Серверное состояние живёт в Pinia Colada. Удалённые коллекции, состояния загрузки и ошибок, refetch и инвалидация не разъезжаются по самодельным store.
• Контракты приходят из OpenAPI-генерации. Запросы, ответы и типы не дублируются вручную, а доменные обёртки остаются тонкими и читаемыми.

За счёт этого UI меньше зависит от сырых transport-моделей, а доменные и презентационные слои не смешиваются между собой.

Аналитика и наблюдаемость

Sauron не ограничивается простым списком сущностей. Проект рассчитан на сценарий, где команде нужно не только видеть данные, но и быстро понимать, что именно происходит с проектом и куда смотреть дальше.

Аналитический слой покрывает:

• агрегирование по временным диапазонам: последние 24 часа, 7 дней, месяц и год
• анализ тональности
• отслеживание негативных и banword-сигналов
• динамику алертов
• производные метрики вроде activity index, sentiment score, weighted score и ratio-based показателей

В результате интерфейс подходит и для повседневной операционной работы, и для обзорной аналитики по проекту.

Локальный запуск

Требования

• Node.js ^20.19.0 || >=22.12.0
• Bun рекомендуется как основной инструмент для установки зависимостей и запуска скриптов

Установка

bun install

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

Frontend ожидает адрес backend-сервиса через переменную окружения:

VITE_BACKEND_URL=http://localhost:8080

Запуск в development

bun run dev

После запуска приложение поднимается через Vite и работает с backend через сгенерированный API-клиент. Access token подставляется централизованно после аутентификации.

Полезные команды

bun run dev
bun run build
bun run preview
bun run type-check
bun run test:unit
bun run test:e2e
bun run storybook
bun run check
bun run fix

Если изменился backend-контракт, клиент можно пересобрать так:

bun run openapi-ts

Качество и тестирование

Проект изначально собран так, чтобы качество кода было частью обычного цикла разработки.

• unit-тесты проверяют доменную и feature-логику
• end-to-end тесты покрывают ключевые пользовательские сценарии
• Storybook позволяет отдельно развивать и проверять UI-компоненты
• линтинг и форматирование автоматизированы через стек Ultracite

Почему проект устроен именно так

Мониторинговый интерфейс почти всегда растёт сразу в нескольких направлениях: добавляются новые источники, фильтры, правила, метрики, страницы и сценарии. Если всё это складывать в несколько больших компонентов или store, код очень быстро теряет форму.

Текущая архитектура выбрана именно для того, чтобы этого избежать:

• сгенерированные контракты уменьшают расхождение между frontend и backend
• доменные обёртки делают использование API предсказуемым и читаемым
• query-driven подход к серверному состоянию убирает дублирующуюся загрузочную логику
• выделенные доменные модели позволяют не тащить transport-формы напрямую в UI
• слои помогают наращивать продукт без превращения проекта в один большой page-store

Текущее состояние

В репозитории уже есть сильная база для полноценного мониторингового интерфейса: аутентификация, сценарий с несколькими организациями, навигация вокруг проектов, интеграции, алерты, словари, аналитика и типизированный API-слой. Это хорошая отправная точка для продукта, в котором операционные экраны и аналитика должны жить в одном фронтенде без хаоса.