Skip to Content
Каталог сервисов

Services catalog

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

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

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

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

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

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

СервисРепозиторийПубликует (префикс)Потребляет (префиксы)
user<host>/user-servicekazmaps.user.*—
review<host>/review-servicekazmaps.review.*—
media<host>/media-servicekazmaps.media.*kazmaps.canon.entity
notification<host>/notification-service—kazmaps.user.*, kazmaps.review.*
editorialkazmaps-main/editorialkazmaps.editorial.*kazmaps.ownership.claim
ownershipkazmaps-main/ownershipkazmaps.ownership.claim— (redirects релиза приходят HTTP-push’ем)
feature-apikazmaps-main/feature-apikazmaps.canon.entitykazmaps.editorial.edit, kazmaps.editorial.release
searchkazmaps-main/search—kazmaps.editorial.edit, kazmaps.editorial.release, kazmaps.review.review (только review.subject_stats_changed)
tileskazmaps-main/tiles—— (Cloudflare Worker + R2, читает релиз конвейера)

Детальный список топиков и 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 (/media/v1/moderation/*), а не событием.

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

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

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

Потребляет события: kazmaps.canon.entity — лента жизненного цикла канона (фото переезжают вслед за слиянием сущности).

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 отсутствует).

Потребляет события: набор бизнес-топиков из других сервисов. Полный список — KAFKA_NOTIFICATION_TOPICS в internal/config/config.go репо сервиса, там же handler’ы и политика идемпотентности.

editorial

Owner: см. who owns what.

Назначение: правки карты поверх канона maps-data: заявки (proposals) с модерацией по ступеням доверия, применение правок в head источника internal, экспорт снапшота правок в конвейер (обратный поток), зеркало релиза (canon.*) и разбор серых пар конфляции. Единственный источник edit.applied для hot lane.

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

  • HTTP API — api/openapi.yaml в репо сервиса.
  • События и контракт с конвейером — docs/contracts.md в репо сервиса.
  • Миграции — migrations/ в репо сервиса.

Публикует события: префикс kazmaps.editorial.* — топики edit, release, proposal, override, report (см. event-catalog).

Потребляет события: kazmaps.ownership.claim (ступень владельца для полосы правок).

ownership

Owner: см. who owns what.

Назначение: реестр владения местами и сетями: обращения (claims) с письмом и проверкой по реестру ЮЛ, членства owner/manager, ступень доверия для editorial (GET /internal/v1/tier), переезд владения по redirects релиза (POST /internal/v1/redirects).

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

  • HTTP API — api/openapi.yaml в репо сервиса.
  • События — internal/event и docs/ownership.md в репо сервиса.
  • Миграции — migrations/ в репо сервиса.

Публикует события: kazmaps.ownership.claim — claim.submitted/verified/rejected/withdrawn/revoked, membership.granted/revoked.

Потребляет события: — (redirects приходят HTTP-push’ем от Job import-release feature-api).

feature-api

Owner: см. who owns what.

Назначение: слой чтения релиза maps-data: канонический конверт фичи по вечному идентификатору (GET /v1/features/{id}), «что в точке» (GET /v1/features/at), редиректы поглощённых идентификаторов, оверлей hot lane поверх релиза. Первый потребитель релизов конвейера; его Job import-release отдаёт redirects релиза в ownership и публикует жизненный цикл сущностей канона.

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

  • HTTP API — api/openapi.yaml в репо сервиса.
  • События — docs/architecture.md в репо сервиса и deploy-data/docs/canon-lifecycle-topic.md.
  • Миграции — migrations/ в репо сервиса.

Публикует события: kazmaps.canon.entity — entity.redirected/retired/restored/closed/reopened.

Потребляет события: kazmaps.editorial.edit (оверлей), kazmaps.editorial.release (порог гашения оверлея).

Owner: см. who owns what.

Назначение: текстовый и фасетный поиск по релизу: зеркало exchange-формы релиза в Postgres, документы в OpenSearch, оверлей hot lane из правок editorial с переиндексацией, рейтинг мест из снимков агрегата отзывов (собственное состояние place_rating, sort=rating в выдаче), словари рубрик и городов релиза (/v2/categories, /v2/cities).

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

  • HTTP API — api/openapi.yaml в репо сервиса.
  • Миграции — migrations/ в репо сервиса.

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

Потребляет события: kazmaps.editorial.edit, kazmaps.editorial.release (группа search.overlay); kazmaps.review.review, только review.subject_stats_changed (группа search.rating).

tiles

Owner: см. who owns what.

Назначение: раздача векторных тайлов и иконок сетей: Cloudflare Worker поверх R2 с kz.pmtiles и assets/logos/* из релиза конвейера. Событий не публикует и не потребляет; обновляется выкладкой релиза.

Источник истины: README.md и docs/ в репо tiles.

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

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

  • Написаны по каноничной структуре — 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.

Last updated on
Обзор архитектурыКаталог событий