Skip to content
BranchesTags

Repository files navigation

RealTimeMap Backend

Go Gin gRPC PostgreSQL Redis Kafka Traefik

Содержание

1. О проекте

RealTimeMap — backend геосоциальной платформы, позволяющей создавать временные метки на карте и взаимодействовать с происходящим вокруг в режиме реального времени.

Что это такое?

Платформа позволяет оставить «цифровой след» в любом месте — отметить событие, встречу, находку или предупреждение, видимое другим пользователям поблизости:

  • Спонтанные мероприятия и встречи
  • Интересные места и находки
  • Важные уведомления для района
  • Точки для общения с людьми рядом

Каждая метка существует ограниченное время, что делает платформу живой и актуальной.

Как это работает?

  1. Откройте карту и посмотрите, что происходит вокруг
  2. Создайте метку с фото, категорией и длительностью
  3. Общайтесь через комментарии и реакции
  4. Зарабатывайте опыт и достижения за активность
  5. Получайте обновления о новых метках в реальном времени

Возможности платформы

Модуль Описание
Метки Геолокационные метки с фото, категориями, пространственной фильтрацией и автоудалением
Социальный профиль Профили, друзья, блокировки, агрегированная статистика
Real-time Мгновенные обновления карты через Socket.IO
Комментарии Вложенные ответы и реакции к меткам
Геймификация Опыт, уровни, достижения за активность
Уведомления Доставка уведомлений пользователям
Аутентификация Регистрация, вход, валидация токенов (ForwardAuth)
Подписки Премиум-возможности, платежи
Документация Внутренний веб-портал с описанием API всех сервисов

2. Архитектура

Проект построен на микросервисной архитектуре с применением принципов Domain-Driven Design (DDD). Каждый сервис автономен: имеет собственную БД, конфигурацию и свой Dockerfile.

┌─────────────────────────────────────────────────────────────┐
│                        Clients                               │
│                  (Web, Mobile, Admin)                        │
└──────────────────────────┬──────────────────────────────────┘
                           │ HTTPS / WebSocket
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                         Traefik                              │
│         (reverse proxy, TLS, CORS, ForwardAuth)              │
│   маршрутизация по PathPrefix → нужный сервис, проверка       │
│   Bearer-токена через auth-service (X-User-* заголовки)       │
└───────┬───────────────┬───────────────┬──────────────┬───────┘
        │ HTTP/Socket.IO│               │              │
        ▼               ▼               ▼              ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ mark-service │ │social-service│ │ gamification │ │   comment    │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
       │   gRPC ◄───────┘                │                │
       │   между сервисами               │                │
       ▼                                 ▼                ▼
┌──────────────┐                  ┌──────────────────────────────┐
│  PostgreSQL  │                  │            Kafka              │
│  + PostGIS   │  ◄── Redis ──►   │   (событийная интеграция:     │
│  (на сервис) │                  │   xp-начисления, статистика)  │
└──────────────┘                  └──────────────────────────────┘

Принципы

  • Независимость сервисов — у каждого микросервиса своя БД, конфиг и независимый деплой
  • DDD-слои — внутри сервиса: domain → app → infrastructure → transport
  • Traefik как точка входа — TLS, CORS и аутентификация (ForwardAuth) вынесены на прокси; сервисы не дублируют эту логику
  • gRPC для внутренней коммуникации — типизированные контракты между сервисами (например, mark-service запрашивает профиль у social-service)
  • Event-driven через Kafka — асинхронная интеграция (начисление опыта, обновление статистики) на базе segmentio/kafka-go
  • Real-time через Socket.IO — обновления карты доставляются клиентам в реальном времени

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

Категория Технологии
Язык Go 1.25
HTTP Framework Gin
Межсервисная связь gRPC + Protocol Buffers
База данных PostgreSQL 16 + PostGIS, доступ через pgx и GORM
Кеширование Redis 7
Событийная шина Kafka (segmentio/kafka-go)
Real-time Socket.IO (doquangtan/socketio)
Reverse Proxy / Gateway Traefik 3.6 (TLS, CORS, ForwardAuth)
Логирование zap
Обработка изображений disintegration/imaging
Контейнеризация Docker, Docker Compose

4. Структура репозитория

RealTimeMap-services/
├── proto/                          # gRPC контракты (.proto)
│   ├── user/
│   ├── profile/
│   ├── mark/
│   ├── comment/
│   └── gamification/
│
├── pkg/                            # Общие переиспользуемые пакеты
│   ├── pb/                         # Сгенерированный protobuf-код
│   ├── logger/                     # Структурированное логирование (zap)
│   ├── config/                     # Загрузка конфигурации
│   ├── database/                   # Подключение к PostgreSQL
│   ├── redis/                      # Redis-клиент
│   ├── transport/                  # Общие транспортные хелперы
│   ├── middleware/                 # Общие middleware
│   ├── apperror/                   # Стандартизированные ошибки приложения
│   ├── clients/                    # gRPC-клиенты к другим сервисам
│   ├── storage/                    # Абстракция хранилища файлов
│   ├── imageprocessor/             # Обработка/ресайз изображений
│   ├── mediavalidator/             # Валидация загружаемых медиа
│   ├── pagination/                 # Пагинация
│   ├── validation/                 # Валидация входных данных
│   ├── helpers/ utils/ date/ types/ runner/   # Прочие утилиты
│
├── services/
│   ├── auth-service/               # Аутентификация (переносится извне)
│   ├── mark-service/               # Метки на карте (ядро платформы)
│   ├── social-service/             # Профили, друзья, блокировки, статистика
│   ├── gamification-service/       # Опыт, уровни, достижения
│   ├── comment-service/            # Комментарии и реакции
│   ├── notification-service/       # Уведомления (в разработке)
│   ├── subsriptions-service/       # Подписки и платежи (в планах)
│   └── docs-service/               # Веб-портал документации API (Vue)
│
├── tools/
│   ├── docgen/                     # Генератор документации из YAML-описаний
│   └── profile-stub/               # Заглушка profile gRPC для локальной разработки
│
├── traefik/
│   ├── traefik.yml                 # Статическая конфигурация прокси
│   └── dynamic.yml                 # Роутеры, middleware (CORS, auth), TLS
│
├── scripts/                        # Общие и сервис-специфичные скрипты
├── docker-compose.yml              # Инфраструктура: Traefik, Postgres, Redis
├── docker-compose.kafka.yml        # Kafka-стек
├── Dockerfile                      # Базовый образ
├── go.mod
└── README.md

Каждый сервис содержит собственный docker-compose.yml (с label-конфигурацией Traefik), Dockerfile и config/. Корневой docker-compose.yml отвечает за общую инфраструктуру.

5. Микросервисы

mark-service

Ядро платформы — управление метками на карте.

  • CRUD операций с метками и категориями
  • Пространственная фильтрация и работа с геоданными (PostGIS)
  • Загрузка и хранение фотографий
  • Автоудаление меток по истечении срока жизни
  • Real-time обновления карты через Socket.IO
  • gRPC-клиент к профилям пользователей

social-service

Социальный слой платформы.

  • Профили пользователей
  • Друзья и связи между пользователями
  • Блокировки пользователей
  • Агрегированная статистика и прогресс
  • gRPC-сервер профилей для других сервисов

gamification-service

Система геймификации.

  • Начисление опыта (XP) по правилам событий
  • Уровни пользователей
  • Достижения
  • Интеграция через Kafka (потребление событий активности)

comment-service

Комментарии и реакции.

  • Комментарии к меткам (с поддержкой вложенности)
  • Реакции (лайки/эмодзи)
  • Фильтрация контента
  • Опциональная интеграция через Kafka

notification-service

Доставка уведомлений пользователям.

Статус: в разработке — каркас сервиса (cmd/) создан, доменная логика переносится.

auth-service

Аутентификация и авторизация: регистрация, вход, валидация токенов. Используется Traefik через ForwardAuth — прокси обращается к /api/v2/auth/token-validate и прокидывает заголовки X-User-Id, X-User-Name, X-User-Ban, X-User-Admin в нижестоящие сервисы.

Статус: существует и работает как отдельный сервис, ещё не перенесён в этот монорепозиторий.

subsriptions-service

Подписки и платежи: тарифные планы, премиум-возможности, история платежей.

Статус: в планах — директория зарезервирована.

docs-service

Внутренний веб-портал документации API (Vue + Vite). Документация ведётся вручную в YAML-файлах внутри каждого сервиса (docs/) и поддерживает описание четырёх типов протоколов: HTTP/REST, Kafka, gRPC и Socket.IO. Также отображает статус доступности сервисов.

6. Общие пакеты и инструменты

pkg/

Переиспользуемые между сервисами пакеты: логирование (logger), конфигурация (config), доступ к БД (database) и Redis (redis), gRPC-клиенты (clients), обработка ошибок (apperror), хранилище и обработка медиа (storage, imageprocessor, mediavalidator), пагинация, валидация и прочие утилиты. Сгенерированный protobuf-код лежит в pkg/pb.

tools/

  • docgen — генерирует документацию из YAML-описаний сервисов для docs-service.
  • profile-stub — лёгкая gRPC-заглушка профилей, чтобы поднимать сервисы локально без полного social-service.

7. Быстрый старт

Требования

  • Docker и Docker Compose
  • Go 1.25+ (для локальной разработки)
  • protoc (для генерации proto)

Настройка

  1. Клонируйте репозиторий
git clone <repo-url>
cd RealTimeMap-services
  1. Создайте .env в корне с переменными инфраструктуры:
POSTGRES_DB=realtimemap
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_secure_password

⚠️ Никогда не коммитьте .env с реальными секретами.

  1. Создайте внешние Docker-сети (используются всеми сервисами):
docker network create web
docker network create service-network
docker network create kafka-network   # если используете Kafka

Запуск

# Инфраструктура (Traefik, Postgres, Redis)
docker-compose up -d

# Kafka (при необходимости)
docker-compose -f docker-compose.kafka.yml up -d

# Запуск конкретного сервиса (на примере mark_action-service)
docker-compose -f services/mark_action-service/docker-compose.yml up -d --build

Каждый сервис маршрутизируется Traefik по своему PathPrefix (см. traefik/dynamic.yml и label'ы в docker-compose.yml сервиса).

Запуск сервиса локально (без Docker)

Настройте config/config.yaml сервиса (хосты БД/Redis/Kafka, gRPC-адреса) и запустите:

cd services/mark_action-service && go run ./cmd

8. Разработка

Структура сервиса (DDD)

service-name/
├── cmd/                    # Точка входа
├── config/                 # config.yaml + загрузка конфигурации
├── internal/
│   ├── app/                # Сборка зависимостей, use-cases, DTO приложения
│   ├── domain/
│   │   ├── model/          # Доменные сущности
│   │   ├── valueobject/    # Value objects
│   │   ├── repository/     # Интерфейсы репозиториев
│   │   ├── service/        # Доменные сервисы
│   │   ├── events/         # Доменные события
│   │   └── domainerrors/   # Доменные ошибки
│   ├── infrastructure/
│   │   ├── persistence/    # Реализация репозиториев (БД)
│   │   ├── grpc/           # gRPC-клиенты к другим сервисам
│   │   └── kafka/          # Kafka producer/consumer
│   ├── transport/
│   │   ├── http/           # HTTP-хендлеры (Gin) + DTO + роуты
│   │   ├── grpc/           # gRPC-сервер
│   │   ├── socket/         # Socket.IO-хендлеры
│   │   └── kafka/          # Обработчики Kafka-сообщений
│   └── mocks/              # Сгенерированные моки (mockery)
├── docs/                   # YAML-описания API для docs-service
├── config.yaml
├── Dockerfile
└── docker-compose.yml      # Traefik-роутеры через labels

gRPC-контракты

.proto-файлы лежат в proto/, сгенерированный код — в pkg/pb/. После изменения контрактов перегенерируйте код через protoc.

Тесты и моки

Моки генерируются через mockery (конфигурация — .mockery.yaml). Тесты — рядом с тестируемым кодом:

# Тесты конкретного сервиса
cd services/mark_action-service && go test ./...

Документация API

Описания endpoints ведутся вручную в docs/*.yaml каждого сервиса, собираются tools/docgen и отображаются в docs-service.

Лицензия

См. LICENSE.

About

МоноРепозиторий с микросервисами

Resources

Readme
MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages