Проект представляет собой сервис, который взаимодействует с базой данных для получения информации о продуктах, их фотографиях и ценах. Сервис также включает функциональность для обработки запросов с использованием ChatAssistant и предоставляет API для взаимодействия с клиентами.
**Product Assistant** is an intelligent backend service that supports product search and recommendation using a Large Language Model (LLM), integrates with Telegram for authorization and notifications, uses Kafka for messaging (price change notifications), and collects traces via OpenTelemetry. The service is containerized using Docker and deployed with Docker Compose (or Kubernetes via separate pipelines).
### Компоненты проекта
---
1.**cmd/assistant/main.go**: Основной файл, который инициализирует конфигурацию, создает сервер на базе Gin и определяет маршруты для обработки запросов.
2.**internal/services/store/Store.go**: Содержит методы для взаимодействия с базой данных, такие как получение продуктов по идентификаторам, получение фотографий и цен по продукту.
3.**internal/services/chatassistant**: Пакет, отвечающий за обработку запросов с использованием ChatAssistant.
4.**internal/config**: Пакет для инициализации конфигурации проекта.
## Table of Contents
### Запуск проекта
-[Overview](#overview)
-[Architecture](#architecture)
-[Components](#components)
-[Authorization via Telegram](#authorization-via-telegram)
-[LLM Integration for Product Querying](#llm-integration-for-product-querying)
Для запуска проекта необходимо выполнить следующие шаги:
---
1.**Сборка Docker-образа**:
Создайте Dockerfile с содержимым:
## Overview
```dockerfile
# Используем базовый образ с Go
FROM golang:1.23.2
Product Assistant Backend is designed to help users search for and compare technical products. Its main features include:
# Устанавливаем рабочую директорию
WORKDIR /app
-**Authorization via Telegram:** Users log in using Telegram, with JWT tokens generated for secure API access.
-**LLM-powered product search:** The system uses a Large Language Model to analyze user queries, combined with vector search (embeddings) to return a list of relevant products.
-**Product Management:** The database stores abstract products (aggregated product data) and parsed products (specific entries from various marketplaces) along with product images.
-**Wishlist:** Users can add products to their wishlist to receive notifications on price changes.
-**Notifications via Kafka and Telegram:** When prices change, the parser triggers Kafka events that are consumed by a notification service which sends alerts via Telegram.
-**Tracing:** OpenTelemetry collects and exports trace data to help monitor the application.
-**Containerized Deployment:** The entire stack is packaged with Docker and can be deployed via Docker Compose (or Kubernetes via separate CI/CD pipelines).
# Копируем файлы проекта
COPY go.mod go.sum ./
RUN go mod download
COPY . .
---
# Сборка приложения
RUN go build -o main ./cmd/assistant
## Architecture
# Указываем порт
EXPOSE 8080
The system is composed of several interacting components:
# Запуск приложения
CMD ["./main"]
```
```mermaid
flowchart LR
A[User Frontend]
B[API Backend]
C[Postgres/TimescaleDB]
D[Parser (Node.js)]
E[LLM Service]
F[Kafka]
G[Notification Service]
H[Telegram Bot]
I[OpenTelemetry Collector]
J[Jaeger UI]
A -->|HTTP API| B
B -->|SQL| C
D -->|Parses & Updates| C
D -->|Price change event| F
F -->|Message| G
G -->|Telegram message| H
B -->|Traces| I
I --> J
```
2.**Сборка и запуск контейнера**:
Выполните команды:
## Components
### Authorization via Telegram
Flow:
```sh
docker build -t myapp .
docker run -p 8080:8080 myapp
```
1. The frontend uses the Telegram Login Widget to authenticate users.
3.**Запуск сервера**:
Сервер будет доступен по адресу `http://localhost:8080`.
2. Telegram returns user data (ID, first name, last name, username, photo URL, auth date, and hash).
### API Маршруты
3. The backend validates the hash, registers the user (if new) or updates their record, and generates a JWT token for further API requests.
-**POST /llm-request**: Обрабатывает запросы с использованием ChatAssistant.
-**GET /get-product**: Возвращает информацию о продукте по его идентификатору.
-**GET /get-matched-ids**: Возвращает список продуктов, соответствующих запросу пользователя.
Key Components:
### Примеры запросов
* TelegramAuthService: Validates Telegram data and generates JWT tokens.
-**POST /llm-request**:
```json
{
"query":"example query"
}
```
* JWT middleware ensures that protected endpoints (e.g., wishlist) are accessed only with valid tokens.
1. When a parsed product’s price changes, the parser triggers an update that calls PublishPriceChange.
2. This method publishes a message to a Kafka topic (e.g., "price_changes").
3. A Kafka consumer in the Notification Service receives the event, retrieves the list of users following the product, and sends a notification via Telegram.
Key Components:
* NotificationService: Publishes and consumes Kafka messages, sends Telegram notifications.
* Kafka Producer/Consumer: Handles messaging.
### Tracing with OpenTelemetry
Flow:
1. All API endpoints are wrapped in OpenTelemetry middleware (otelhttp.NewHandler).
2. Internal operations may also create manual spans.
3. The collector exports traces to Jaeger, where they can be visualized.
Key Components:
* diagnostics.NewOTel: Configures and initializes the tracer provider.
* Integration via otelhttp and manual span creation in critical sections.
### Docker Compose Deployment
* Local Deployment:
The entire stack (DB, Kafka, OTEL Collector, Jaeger, Parser, Ollama, and API Backend) is defined in a docker-compose.yml file, enabling local testing and development.
* Key Components in Docker Compose:
* Containers for TimescaleDB, Kafka, Zookeeper, OTEL Collector, Jaeger, Ollama, and your API server.
* Volumes for persistent data.
* Environment variables to configure connectivity between services.
## Installation & Setup
### Prerequisites
* Docker & Docker Compose:
Ensure Docker is installed and Docker Compose is available.
* Git:
For cloning the repository.
* GitLab Runner:
For CI/CD integration (if deploying via GitLab).
### Clone Repository
```bash
git clone <repository-url>
cd <repository-directory>
```
### Environment Variables
Create a .env file (or set environment variables via your deployment system) with the following keys:
