Перейти к содержанию

Services catalog

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

Этот каталог — источник правды для навигации. Если ты не знаешь, в каком сервисе искать логику — начни отсюда. Если ты добавляешь новый сервис — первым делом заведи запись здесь, ещё до первого PR в сервис-репо.

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

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

Связка с event-catalog.md: здесь сервис указан с именами своих событий (labels для навигации), а источник правды по событиям — event-catalog.md. Если переименовал событие — правь оба файла.

user

Репозиторий: <host>/user-service (приватный) Owner: см. onboarding/04-who-owns-what.md Порт (local dev): 8001 Описание: регистрация и логин пользователя, выпуск и ротация refresh-token'ов, OAuth (внешние провайдеры), чтение и обновление профиля, admin-операции (ban / unban, смена уровня), смена пароля. Единственный сервис, который выпускает JWT — все остальные сервисы получают уже подписанные заголовки от gateway.

Выпускает события: - user.registered - user.updated - user.banned - user.unbanned - user.level_changed

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

HTTP API: - /v1/auth/* — регистрация, логин, refresh, OAuth callback'и. - /v1/users/* — профиль текущего пользователя. - /v1/admin/* — admin-операции (require role admin). - /internal/* — lookup по id для других сервисов, валидация токенов.

Внешние зависимости: - Postgres (схема auth) — users, sessions, outbox, admin change log. - Redis — denylist отозванных access-токенов, ratelimit per-user на login. - Kafka — publish через outbox + forwarder.

Референс в коде: internal/handler/router.go, internal/service/auth.go, internal/event/events.go.

review

Репозиторий: <host>/review-service (приватный) Owner: см. onboarding/04-who-owns-what.md Порт (local dev): 8007 Описание: CRUD отзывов к местам (rating + text + photos), реакции (лайки/дизлайки), реплаи владельца места на отзыв, публичный SSE-поток обновления гистограмм рейтинга (подписка из frontend'а для «живого» счётчика на странице места).

Выпускает события: - review.created - review.updated - review.deleted - review.replied

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

HTTP API: - /v1/reviews/* — публичный CRUD + реакции. - /v1/places/{id}/reviews — листинг отзывов к месту (cursor-based). - /v1/reviews/{id}/reply — реплай владельца. - /v1/places/{id}/rating/stream — SSE-поток histogram рейтинга. - /internal/* — internal lookup (например, для media: проверить, что review существует перед прикреплением фото).

Внешние зависимости: - Postgres — reviews, reactions, replies, outbox. - Redis — ratelimit на создание отзыва per-user, cache гистограмм. - Kafka — publish event'ов review.*, через outbox + forwarder.

Референс в коде: internal/event/publisher.go, internal/service/review.go, internal/service/reply.go, internal/sse/ (SSE-стрим гистограмм).

media

Репозиторий: <host>/media-service (приватный) Owner: см. onboarding/04-who-owns-what.md Порт (local dev): 8008 Описание: загрузка фото (multipart upload для больших файлов), процессинг через libvips (ресайз, WEBP, создание thumbnails), подписанные URL для чтения, tagging фото, orphan cleanup (фото, не привязанные к сущности через TTL, удаляются фоновым worker'ом). Асинхронно получает результаты модерации и помечает фото.

Выпускает события: - media.processing (internal: задача процессинга для worker'а того же сервиса; один топик, одно потребление — внутренний pipeline, не межсервисное API) - photo.uploaded - photo.deleted - photo.tagged

Потребляет события: - moderation.approved — пометить фото как прошедшее модерацию. - moderation.rejected — пометить фото как отклонённое, причина сохраняется.

HTTP API: - /v1/media/upload/* — инициирование сессии, chunk upload, commit. - /v1/media/{id} — GET подписанный URL, DELETE. - /v1/media/{id}/tags — PUT tags. - /internal/* — internal lookup фото по id.

Внешние зависимости: - Postgres — photos, upload_sessions, photo_tags, outbox. - MinIO — object storage для оригиналов и производных. - Redis — дедуп сессий, ratelimit. - Kafka — publish upload-событий, consume moderation-результатов. - libvips — нативная библиотека обработки изображений.

Референс в коде: internal/event/events.go, internal/service/upload.go, internal/worker/processor.go, internal/event/consumer.go.

notification

Репозиторий: <host>/notification-service (приватный) Owner: см. onboarding/04-who-owns-what.md Порт (local dev): 8013 Описание: отправка уведомлений по 4 каналам (push через FCM/APNs, email через SMTP, SMS через Mobizon, in-app — сохранение в БД для показа в клиенте). Шаблоны с i18n. Consent per-канал per-пользователь. Дедупликация повторных событий.

Выпускает события: —

Потребляет события: подписывается на широкий набор бизнес-топиков из других сервисов и превращает их в уведомления. На момент каталогизации consumer подписан на: - review.replied (из review) - user.level_changed (из user) - moderation.rejected (из media) - user.push_token.created, user.push_token.updated, user.push_token.deleted (из user; синхронизация push-токенов)

Остальные топики из списка KAFKA_NOTIFICATION_TOPICS (booking.*, queue.*, correction.*, achievement.*, coupon.*, safety_report.* и т.п.) — зарезервированы под будущие сервисы; пока эти сервисы не поднялись, consumer их просто не получает. См. internal/config/config.go, список NotificationTopics.

HTTP API: - /v1/notifications/* — история для пользователя, mark-as-read. - /v1/settings/* — consent-настройки per канал. - /internal/* — ad-hoc отправка уведомления (например, password-reset email из user-сервиса).

Внешние зависимости: - Postgres — notifications, push_tokens, settings, dedup. - Redis — cache consent-настроек, dedup-ключи. - Kafka — consume only (publish'ера как такового нет). - FCM (push-provider), APNs (iOS push). - SMTP relay для email. - Mobizon HTTP API для SMS. - user-сервис (HTTP internal) — разрешение user_id → email/phone.

Референс в коде: internal/event/handler.go, internal/service/notification.go, internal/delivery/*.

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

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

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

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