🏗️ Stroy1Click

Онлайн-магазин строительных материалов

Stroy1Click — высоконагруженный, отказоустойчивый e-commerce проект с микросервисной архитектурой, современной инфраструктурой, полной наблюдаемостью.

---

🚀 Возможности

• 🛒 Каталог категорий, подкатегорий, типов продуктов, товаров, корзина, заказы
• 👤 Пользователи, роли, авторизация и безопасность
• ⚡ Высокая производительность и отказоустойчивость
• 🧠 Кэширование и распределённые блокировки
• 🔍 Полная наблюдаемость: метрики, трассировка, логи
• 🧪 Интеграционные и контейнерные тесты
• ☁️ Полностью готов к деплою в Kubernetes

---

🧩 Архитектура

Основные принципы архитектуры:

• микросервисный подход
• горизонтальное масштабирование
• устойчивость к сбоям за счёт использования Resilience4j CircuitBreaker
• безопасность на основе JWT-аутентификации между микросервисами
• централизованный мониторинг и распределённая трассировка на базе OpenTelemetry
• автоматизированный CI/CD
• Database-per-Service - каждый сервис владеет своей базой данных
• Outbox Pattern для надёжной доставки событий и согласованности данных (используется между ProductService и SearchService)
• Реактивное программирование (используется в Notification Service)
• Redis-кэширование для повышения производительности и снижения нагрузки на БД

---

🛠️ Технологический стек

️ Frontend

• JavaScript
• HTML / CSS
• BFF (Backend for Frontend) - Spring Boot
• Thymeleaf

Backend

• Java / Spring Boot
  • Spring Web (Spring MVC)
  • Spring Data JPA
  • Spring Security
  • Spring Validation
  • Spring WebFlux
  • Spring Actuator
  • Spring for Apache Kafka
  • Spring Boot Starter Mail
  • Spring Boot Starter Freemarker
• Resilience4j (CircuitBreaker, RateLimiter)
• Redisson
• Flyway
• ModelMapper
• Lombok
• AWS Java SDK

📦 Собственные библиотеки (Custom Shared Libraries)

Для унификации кода и повторного использования логики в микросервисной среде были разработаны следующие модули:

• Common Library:
  • Общие модели данных: DTO, Command, Event.
  • Exceptions
  • Работа с JWT: JwtService.
  • Валидация: логика ImageValidator.
  • Утилитные классы: конфигурация ModelMapper, логирование и обработка ошибок ValidationErrorUtils.
• Outbox Core:
  • Централизованная логика для реализации паттерна Transactional Outbox.
  • Обеспечивает атомарность сохранения бизнес-данных и событий для отправки.
• Outbox Consumer Core:
  • Логика для идемпотентной обработки сообщений из Kafka.
  • Защита от дубликатов при повторной доставке (Exactly-once processing logic).

Search Service (AI Service)

• Python
• AI / Search processing

Telegram Bot

• Go
  • Chi
  • Cors

Infrastructure & DevOps

• Docker
• Kubernetes
• Redis
• PostgreSQL
• S3
• Apache Kafka

Observability & Monitoring

• OpenTelemetry
• ElasticSearch
• Tempo
• Prometheus
• Grafana

Testing

• JUnit
• Mockito
• Testcontainers

Documentation

• Swagger / OpenAPI

---

🛡️ Resilience & Fault Tolerance

• CircuitBreaker для внешних вызовов
• RateLimiter для защиты от перегрузки
• Redis-кэш для уменьшения нагрузки на БД
• Graceful degradation при отказах сервисов

🔐 Security Architecture

• Аутентификация и авторизация на основе JWT
• JWT используется для защищённого взаимодействия между микросервисами
• Ingress Controller выполняет роль API Gateway
• Каждый входящий запрос проходит через Ingress, где:
  • извлекается JWT-токен
  • выполняется валидация токена через JWT Validator Service
  • проверяются права доступа
• Разграничение прав доступа на уровне API Gateway / BFF
• Secure secrets management

👁️ Observability

• Метрики - Prometheus
• Трассировка - OpenTelemetry + Tempo
• Логи - ElasticSearch
• Визуализация - Grafana

⚡ Reactive & Notification Flow

В системе используется реактивное программирование в Notification Service на базе Spring WebFlux и Server-Sent Events (SSE).

Поток событий при создании заказа:

1. Order Service создаёт заказ
2. Notification Service получает сообщение от Apache Kafka
3. Notification Service публикует событие через SSE
4. Административная консоль в реальном времени отображает появление нового заказа

---

🧬 Data & Event Flow

Transactional Outbox Pattern

В проекте используется паттерн Transactional Outbox для обеспечения гарантированной доставки сообщений между микросервисами (например, от Product Service к Search Service).

Механизм работы:

1. Сервис обновляет состояние сущности в БД и одновременно сохраняет событие в таблицу outbox в рамках одной транзакции.
2. Отдельный процесс считывает события из outbox и публикует их в Apache Kafka.
3. Микросервисы-потребители (Consumer) получают сообщения и обрабатывают их, используя Outbox Consumer Core для предотвращения дублирования действий.

Данный подход гарантирует Eventual Consistency (согласованность в конечном счете) и исключает потерю данных при сбоях брокера или сети.

☁️ Deployment

Проект развернут в облачной инфраструктуре timeweb.cloud с использованием Docker и Kubernetes. Для локального развёртывания перейдите к observability-infrastructure/docker-compose.yaml.

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

После запуска микросервиса Swagger доступен по адресу:

http://localhost:{port}/swagger-ui/index.html

🧠 AI-Service (Search & Intelligence)

Высокопроизводительный микросервис на Python (FastAPI), реализующий логику семантического поиска и интеллектуальной обработки товаров.

🛠 Стек технологий

• Framework: FastAPI (Asynchronous).
• Machine Learning: sentence-transformers (модель paraphrase-multilingual-MiniLM-L12-v2).
• Vector Engine: Elasticsearch 8.x (Dense Vector storage).
• Database: PostgreSQL (SQLAlchemy 2.0 Async) для надежного хранения метаданных.

🚀 Основные функции и возможности

• Hybrid Data Storage: Сервис поддерживает актуальную копию данных в PostgreSQL (схема search_schema) и синхронизирует её с поисковым индексом Elasticsearch.
• Semantic Search (k-NN): Поиск выполняется не по ключевым словам, а по смысловому сходству векторов (Cosine Similarity). Это позволяет находить релевантные товары даже при отсутствии точных совпадений в тексте.
• Multilingual Support: Используемая модель трансформера оптимизирована для работы с русским и английским языками.
• Outbox Synchronization: Интеграция с Java-микросервисами через обработку событий OutboxMessageDto, что гарантирует согласованность данных (Eventual Consistency).

🧬 Логика потока данных (Data Flow)

1. Ingestion: Приложение принимает событие (создание/обновление товара) через REST-эндпоинт.
2. Embedding: Текстовое описание товара преобразуется в вектор из 384 чисел.
3. Indexing: Данные сохраняются в индекс products_ai_search вместе с вектором.
4. Search: При поисковом запросе сервис векторизует запрос пользователя и находит ТОП-10 ближайших соседей в векторном пространстве Elasticsearch.

🔍 Monitoring & Observability

Сервисы мониторинга и наблюдаемости доступны по адресам:

Grafana - http://localhost:3000

Prometheus - http://localhost:9095/query

ElasticSearch - http://localhost:9200