От хаоса к объектам: как переделали API для трендов

Регистрируем API эндпоинт: как архитектура трендов выросла из хаоса документации

Мне нужно было разобраться с проектом trend-analysis — системой для отслеживания трендов из GitHub и Hacker News. Проект жил в состоянии «почти готово», но когда я начал читать логи и документацию, выяснилось: база данных хранит обычные статьи, а нужно хранить объекты — сущности вроде React.js или ChatGPT, за которыми стоит десятки упоминаний.

Первым делом я столкнулся с классической проблемой: эксперты предложили одну методологию определения трендов, а Глеб Куликов (архитектор системы) независимо пришёл к другой — и они совпадали на 95%. Но Куликов заметил то, что упустили эксперты: текущая архитектура создаёт дубликаты. Одна статья о React — один тренд, вторая статья о React — второй тренд. Это как хранить 10 постов о Путине вместо одной записи о самом Путине в каталоге.

Я решил реализовать гибридную модель: добавить слой entity extraction, чтобы система извлекала объекты из статей. Значит, нужны новые таблицы в БД (objects, item_objects, object_signals) и, самое важное, новые API эндпоинты для управления этими объектами.

Вот тут начинается интересная часть. API эндпоинты я размещал в api/auth/routes.py — стандартное место в проекте. Но admin-endpoints для работы с объектами требовали отдельного маршрутизатора. Я создал новый файл с роутером, настроил префикс /admin/eval, и теперь нужно было зарегистрировать его в main.py.

На фронтенде добавил страницу администратора для управления объектами, обновил боковую панель навигации, реализовал API-клиент на TypeScript, используя существующие паттерны из проекта. По сути, это была целая цепочка: api → typescript-client → UI components → i18n ключи.

Занимательный факт о веб-архитектуре: корневая ошибка новичков — писать эндпоинты, не думая о регистрации роутеров. Flask и FastAPI не магическим образом находят ваши функции. Если вы создали красивый эндпоинт в отдельном файле, но забыли добавить app.include_router() в main.py — для клиента это будет 404 Not Found. Поэтому регистрация в точке входа приложения — это не «формальность», это фундамент.

В итоге система сегодня: - Не ломает текущую функциональность (backward compatible) - Может извлекать объекты из потока статей - Отслеживает свойства объектов: количество упоминаний, интенсивность сентимента, иерархию категорий - Готова к полной дедупликации в Q3–Q4

Документировал всё в KULIKOVS-METHODOLOGY-ANALYSIS.md — отчёт на 5 фаз имплементации. Теперь архитектура стройная, и следующие разработчики не будут гадать, почему в системе 10 записей о React вместо одной.

😄 Почему Ansible расстался с разработчиком? Слишком много зависимостей в отношениях.