Services catalog

Каталог сервисов, которые сейчас живут в проде. Одна запись на один сервис: где лежит код, кто владелец, что делает, префиксы событий, которые публикует и потребляет.

Эта страница — directory. Детальные контракты (HTTP endpoints, payload’ы событий, миграции) живут в репозитории каждого сервиса. Если ты не знаешь, в каком сервисе искать логику — начни отсюда, дальше переходи по ссылке на репо.

Как поддерживать каталог

• Новый сервис готов к первому релизу → добавь запись сюда тем же PR, которым меняешь инфру или первый раз деплоишь.
• Сервис переехал в другой репозиторий / сменил владельца → обнови запись.
• Сервис помечен deprecated → добавь пометку status: deprecated и дату. В каталоге он остаётся, пока трафик не ушёл.
• Сервис retired → удали запись. До этого — не удаляй, иначе команда потеряет контекст.

Шаблон записи и обязательная структура README сервиса — в conventions/service-readme. Источник правды по HTTP API и событиям конкретного сервиса — README в его репозитории.

Сводная таблица

Детальный список топиков и envelope — в event-catalog.

user

Owner: см. who owns what.

Назначение: аутентификация (JWT, OAuth, refresh-ротация), профили пользователей, admin-операции (ban / unban, смена уровня), revoke токенов. Единственный сервис, который выпускает JWT.

Источник истины:

• HTTP API — README.md в репо сервиса.
• События — docs/events.md в репо сервиса.
• Миграции — migrations/ в репо сервиса.

Публикует события: префикс kazmaps.user.* (см. event-catalog).

Потребляет события: —

review

Owner: см. who owns what.

Назначение: отзывы к местам (CRUD, рейтинг, реакции, реплаи владельца места), публичный поток обновления гистограмм рейтинга.

Источник истины:

• HTTP API — README.md в репо сервиса.
• События — docs/events.md в репо сервиса.
• Миграции — migrations/ в репо сервиса.

Публикует события: префикс kazmaps.review.* (см. event-catalog).

Потребляет события: —

media

Owner: см. who owns what.

Назначение: загрузка и процессинг фото (resize, thumbnails, WEBP), подписанные URL для чтения, tagging, orphan-cleanup. Результаты модерации применяются асинхронно через события.

Источник истины:

• HTTP API — README.md в репо сервиса.
• События — docs/events.md в репо сервиса.
• Миграции — migrations/ в репо сервиса.

Публикует события: префикс kazmaps.media.* (см. event-catalog).

Потребляет события: префикс kazmaps.moderation.* (publisher — внешний модерационный сервис).

notification

Owner: see who owns what.

Назначение: доставка уведомлений по каналам push / email / sms / in-app. Шаблоны с i18n, consent per-канал per-пользователь, дедупликация повторных событий.

Источник истины:

• HTTP API — README.md в репо сервиса.
• События (consumer-side) — docs/events.md в репо сервиса.
• Миграции — migrations/ в репо сервиса.

Публикует события: — (consumer-only сервис, outbox отсутствует).

Потребляет события: широкий набор бизнес-префиксов из других сервисов — kazmaps.user.*, kazmaps.review.*, kazmaps.media.*, kazmaps.moderation.*. Полный список handler’ов и политика идемпотентности — в docs/events.md репо сервиса.

Общие правила

Все четыре сервиса:

• Написаны по каноничной структуре — conventions/project-layout.
• Используют log/slog JSON → stdout — conventions/logging.
• Общаются через HTTP (/internal/*) и Kafka — architecture-overview.
• Имеют outbox-таблицу в своей БД (кроме notification, у которого нет исходящих событий).
• Имеют /healthz, /readyz, /metrics.
• README соответствует шаблону conventions/service-readme.

Добавляешь пятый сервис? Открой how-to/add-new-service и пройди по шагам. Запись в этот каталог — часть чеклиста запуска нового сервиса.

Источник истины

Детальные контракты HTTP и событий живут в репо соответствующего сервиса; если handbook расходится с README сервиса, источник истины — README сервиса. Единый шаблон README — в conventions/service-readme.