feat: initial commit

2026-04-16 19:39:02 +02:00
commit 50d1686b1e
44 changed files with 2089 additions and 0 deletions
--- a/.env.example
+++ b/.env.example
@@ -0,0 +1,18 @@
 TELEGRAM_BOT_TOKEN=your_bot_token_here
 BOT_MODE=polling
 TELEGRAM_DEBUG=false
 N8N_BASE_URL=http://localhost:5678
 N8N_AUTH_TOKEN=
 OPENAI_API_KEY=your_openai_key_here
 STT_PROVIDER=openai
 WHISPER_MODEL=whisper-1
 WHISPER_LANGUAGE=
 REDIS_URL=redis://localhost:6379
 SESSION_TTL=24
 LOG_LEVEL=info
 LOG_FORMAT=json
 SERVER_PORT=8080
--- a/README.md
+++ b/README.md
@@ -0,0 +1,304 @@
 # gw_telegram
 Bramka Telegram do n8n i systemów agentów AI. Bot przyjmuje wiadomości tekstowe i głosowe od użytkowników i routuje je do odpowiednich workflow w n8n lub agentów AI.
 ## Funkcje
 - **Wiadomości tekstowe** — routing oparty na regułach regex do dowolnego workflow n8n
 - **Wiadomości głosowe** — pipeline: pobieranie OGG → konwersja ffmpeg (WAV 16kHz) → transkrypcja Whisper API → routing jak tekst
 - **Sesje użytkowników** — historia konwersacji przechowywana w Redis z konfigurowalnym TTL
 - **Graceful shutdown** — obsługa sygnałów `SIGINT`/`SIGTERM`, bot kończy obsługę aktualnych wiadomości przed zatrzymaniem
 - **Tryby pracy** — polling (domyślny) lub webhook
 ## Architektura
 Projekt stosuje **Clean Architecture** z pełnym oddzieleniem warstw:
 ```
 cmd/bot/main.go              # composition root — łączy wszystkie warstwy
 internal/
  domain/                    # logika biznesowa, zero zależności zewnętrznych
    entity/                  # modele: Message, Session, Intent, Route, WorkflowRequest
    port/                    # interfejsy (bramy zależności)
    apperror/                # typowane błędy domenowe
  application/               # przypadki użycia
    usecase/                 # HandleTextMessage, HandleVoiceMessage
    dto/                     # obiekty transferu danych
  infrastructure/            # implementacje portów
    telegram/                # BotGateway, UpdatePoller, FileDownloader
    n8n/                     # WebhookDispatcher
    speech/                  # OpenAIWhisper, FFmpegConverter
    router/                  # RuleBasedRouter
    storage/                 # RedisSessionStore
  interfaces/                # warstwa wejściowa
    telegram_handler.go      # mapowanie update → use case
    health_handler.go        # endpointy /health i /ready
  config/                    # ładowanie konfiguracji z env
 test/testutil/               # fake'i dla wszystkich portów (TDD)
 deploy/                      # Dockerfile, docker-compose.yml
 ```
 ### Pipeline wiadomości głosowej
 ```
 Telegram Voice Update
       │
       ▼
 TelegramHandler.Handle()
       │
       ▼
 HandleVoiceMessage.Execute()
  1. SendTyping (wskaźnik pisania)
  2. FileDownloader.Download(fileID)  → OGG Opus bytes
  3. FFmpegConverter.Convert()        → WAV 16kHz mono
  4. OpenAIWhisper.Transcribe()       → tekst
       │
       ▼
 HandleTextMessage.Execute()          → routing → n8n → odpowiedź
 ```
 ### Kontrakt JSON z n8n
 Bot wysyła do webhooka n8n:
 ```json
 {
  "request_id": "uuid-v4",
  "chat_id": 123456789,
  "user_id": 987654321,
  "username": "jankowalski",
  "message_text": "Gdzie jest moje zamówienie #12345?",
  "intent_name": "order_inquiry",
  "timestamp": "2026-04-16T10:00:00Z",
  "metadata": {
    "route_target_type": "n8n"
  }
 }
 ```
 n8n odpowiada:
 ```json
 {
  "reply": "Twoje zamówienie #12345 jest w drodze.",
  "actions": [],
  "next_workflow": null
 }
 ```
 Jeśli n8n zwróci surowy tekst (nie JSON), bot wyśle go bezpośrednio do użytkownika.
 ## Wymagania
 - Go 1.22+
 - Redis 7+
 - ffmpeg (wymagany do obsługi wiadomości głosowych)
 - [Task](https://taskfile.dev) (`go install github.com/go-task/task/v3/cmd/task@latest`)
 - Token bota Telegram ([@BotFather](https://t.me/BotFather))
 - Klucz API OpenAI (do transkrypcji głosu)
 - Działająca instancja n8n
 ## Konfiguracja
 Konfiguracja odbywa się wyłącznie przez zmienne środowiskowe. Skopiuj `.env.example` jako punkt startowy:
 ```bash
 cp .env.example .env
 ```
 ### Zmienne środowiskowe
 #### Bot Telegram (wymagane)
 | Zmienna | Domyślna | Opis |
 |---|---|---|
 | `TELEGRAM_BOT_TOKEN` | — | Token bota z @BotFather |
 | `BOT_MODE` | `polling` | Tryb pracy: `polling` lub `webhook` |
 | `TELEGRAM_WEBHOOK_URL` | — | URL webhooka (tylko dla `BOT_MODE=webhook`) |
 | `TELEGRAM_DEBUG` | `false` | Włącza szczegółowe logi Telegram API |
 #### n8n (wymagane)
 | Zmienna | Domyślna | Opis |
 |---|---|---|
 | `N8N_BASE_URL` | — | Bazowy URL instancji n8n, np. `http://localhost:5678` |
 | `N8N_AUTH_TOKEN` | — | Token Bearer do uwierzytelniania webhooka |
 | `N8N_TIMEOUT` | `30` | Timeout żądania do n8n (sekundy) |
 | `N8N_RETRY_COUNT` | `3` | Liczba ponownych prób przy błędzie |
 #### Speech-to-Text
 | Zmienna | Domyślna | Opis |
 |---|---|---|
 | `STT_PROVIDER` | `openai` | Dostawca transkrypcji: `openai` |
 | `OPENAI_API_KEY` | — | Klucz API OpenAI (wymagany jeśli `STT_PROVIDER=openai`) |
 | `WHISPER_MODEL` | `whisper-1` | Model Whisper |
 | `WHISPER_LANGUAGE` | — | Kod języka BCP-47 (np. `pl`, `en`). Puste = autodetekcja |
 | `FFMPEG_PATH` | `ffmpeg` | Ścieżka do binarki ffmpeg |
 #### Redis
 | Zmienna | Domyślna | Opis |
 |---|---|---|
 | `REDIS_URL` | `redis://localhost:6379` | URL połączenia z Redis |
 | `SESSION_TTL` | `24` | Czas życia sesji użytkownika (godziny) |
 #### Serwer HTTP
 | Zmienna | Domyślna | Opis |
 |---|---|---|
 | `SERVER_PORT` | `8080` | Port serwera HTTP (`/health`, `/ready`) |
 #### Logowanie
 | Zmienna | Domyślna | Opis |
 |---|---|---|
 | `LOG_LEVEL` | `info` | Poziom logów: `debug`, `info`, `warn`, `error` |
 | `LOG_FORMAT` | `json` | Format logów: `json` lub `text` |
 ## Uruchomienie
 ### Lokalne (bez Dockera)
 Wymagania: Go 1.22+, Redis, ffmpeg zainstalowane lokalnie.
 ```bash
 # 1. Sklonuj i przejdź do katalogu
 git clone <repo-url>
 cd gw_telegram
 # 2. Pobierz zależności
 go mod download
 # 3. Skonfiguruj zmienne środowiskowe
 cp .env.example .env
 # edytuj .env — uzupełnij TELEGRAM_BOT_TOKEN, N8N_BASE_URL, OPENAI_API_KEY
 # 4. Eksportuj zmienne
 export $(grep -v '^#' .env | xargs)
 # 5. Uruchom
 task run
 ```
 ### Docker Compose (zalecane)
 ```bash
 # 1. Skonfiguruj zmienne
 cp .env.example .env
 # uzupełnij .env
 # 2. Zbuduj i uruchom
 task docker:up
 # 3. Sprawdź logi
 docker compose -f deploy/docker-compose.yml logs -f bot
 # 4. Zatrzymaj
 task docker:down
 ```
 Docker Compose uruchamia bota razem z Redisem. Redis automatycznie persystuje dane sesji w woluminie `redis_data`.
 ### Binarka produkcyjna
 ```bash
 task build
 # binarka: ./bin/bot
 TELEGRAM_BOT_TOKEN=xxx N8N_BASE_URL=http://n8n:5678 ./bin/bot
 ```
 ## Routing wiadomości
 Routing jest oparty na regułach regex z priorytetem. Reguły są definiowane w kodzie (`cmd/bot/main.go`) i dopasowywane od najwyższego priorytetu. Pierwsza pasująca reguła wygrywa.
 ### Domyślne reguły
 | Pattern | Intent | Target | Priorytet |
 |---|---|---|---|
 | `^/start` | `start` | builtin | 100 |
 | `^/help` | `help` | builtin | 100 |
 | `.*` | `general_query` | n8n: `default` | 0 |
 ### Dodawanie nowego workflow n8n
 1. Dodaj regułę w `cmd/bot/main.go`:
 ```go
 {
    Pattern:    regexp.MustCompile(`(?i)zamówienie|order`),
    IntentName: "order_inquiry",
    Target: entity.RouteTarget{
        Type:       entity.RouteTargetN8n,
        WorkflowID: "order-webhook",
    },
    Priority: 50,
 },
 ```
 2. Dodaj konfigurację workflow w mapie `workflows`:
 ```go
 workflows := map[string]n8n.WorkflowConfig{
    "default": {
        WebhookURL: cfg.N8n.BaseURL + "/webhook/default",
        AuthToken:  cfg.N8n.AuthToken,
    },
    "order-webhook": {
        WebhookURL: cfg.N8n.BaseURL + "/webhook/order-inquiry",
        AuthToken:  cfg.N8n.AuthToken,
    },
 }
 ```
 ## Testy
 ```bash
 # Testy jednostkowe
 task test
 # Testy z raportem pokrycia (HTML)
 task test:cover
 # otwórz coverage.html
 # Testy integracyjne (wymaga Dockera)
 task test:int
 ```
 Projekt stosuje TDD. Każdy przypadek użycia ma testy oparte na ręcznie pisanych fake'ach portów (`test/testutil/`), bez generowanych mocków.
 ### Pokrycie testami
 | Pakiet | Testowane scenariusze |
 |---|---|
 | `HandleTextMessage` | Happy path, pusty tekst, brak trasy, błąd dispatchera, persystencja sesji |
 | `HandleVoiceMessage` | Happy path, błąd pobierania pliku, błąd transkrypcji, konwersja audio |
 ## Linting
 ```bash
 task lint
 ```
 Projekt używa `golangci-lint`. Konfiguracja w `.golangci.yml`.
 ## Health Check
 Serwer HTTP (`SERVER_PORT`) udostępnia:
 - `GET /health` — zawsze zwraca `200 OK` jeśli proces działa
 - `GET /ready` — zwraca `200 OK` gdy połączenie z Telegram API i Redis jest aktywne
 Przydatne do probes w Kubernetes i healthcheck w Docker Compose.
 ## Zależności
 | Biblioteka | Zastosowanie |
 |---|---|
 | `go-telegram-bot-api/v5` | Telegram Bot API (polling + wysyłanie wiadomości) |
 | `kelseyhightower/envconfig` | Ładowanie konfiguracji ze zmiennych środowiskowych |
 | `redis/go-redis/v9` | Klient Redis do przechowywania sesji |
 | `google/uuid` | Generowanie RequestID |
 | `stretchr/testify` | Asercje w testach |
 | `log/slog` (stdlib) | Strukturalne logowanie JSON |
--- a/Taskfile.yml
+++ b/Taskfile.yml
@@ -0,0 +1,53 @@
 version: "3"
 tasks:
  build:
    desc: Build the bot binary
    cmds:
      - go build -o bin/bot ./cmd/bot
  test:
    desc: Run unit tests
    cmds:
      - go test ./...
  test:cover:
    desc: Run unit tests with HTML coverage report
    cmds:
      - go test -coverprofile=coverage.out ./...
      - go tool cover -html=coverage.out -o coverage.html
  test:int:
    desc: Run integration tests (requires Docker)
    cmds:
      - go test -tags=integration ./test/integration/...
  lint:
    desc: Run golangci-lint
    cmds:
      - golangci-lint run ./...
  run:
    desc: Run the bot locally
    cmds:
      - go run ./cmd/bot
  tidy:
    desc: Tidy go modules
    cmds:
      - go mod tidy
  docker:build:
    desc: Build Docker image
    cmds:
      - docker build -t gw_telegram -f deploy/Dockerfile .
  docker:up:
    desc: Start services via docker compose
    cmds:
      - docker compose -f deploy/docker-compose.yml up -d
  docker:down:
    desc: Stop services via docker compose
    cmds:
      - docker compose -f deploy/docker-compose.yml down
--- a/cmd/bot/main.go
+++ b/cmd/bot/main.go
@@ -0,0 +1,125 @@
 package main
 import (
 	"context"
 	"log/slog"
 	"os"
 	"os/signal"
 	"regexp"
 	"syscall"
 	tgbotapi "github.com/go-telegram-bot-api/telegram-bot-api/v5"
 	"github.com/redis/go-redis/v9"
 	"github.com/paramah/gw_telegram/internal/application/usecase"
 	"github.com/paramah/gw_telegram/internal/config"
 	"github.com/paramah/gw_telegram/internal/domain/entity"
 	"github.com/paramah/gw_telegram/internal/infrastructure/n8n"
 	"github.com/paramah/gw_telegram/internal/infrastructure/router"
 	"github.com/paramah/gw_telegram/internal/infrastructure/speech"
 	"github.com/paramah/gw_telegram/internal/infrastructure/storage"
 	infratelegram "github.com/paramah/gw_telegram/internal/infrastructure/telegram"
 	"github.com/paramah/gw_telegram/internal/interfaces"
 )
 func main() {
 	cfg := config.MustLoad()
 	logger := newLogger(cfg.Log)
 	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 	defer cancel()
 	// Telegram bot
 	bot, err := tgbotapi.NewBotAPI(cfg.Bot.Token)
 	if err != nil {
 		logger.Error("failed to create telegram bot", "error", err)
 		os.Exit(1)
 	}
 	bot.Debug = cfg.Bot.Debug
 	logger.Info("telegram bot authorized", "username", bot.Self.UserName)
 	// Redis
 	redisOpts, err := redis.ParseURL(cfg.Redis.URL)
 	if err != nil {
 		logger.Error("invalid redis url", "error", err)
 		os.Exit(1)
 	}
 	redisClient := redis.NewClient(redisOpts)
 	// Infrastructure
 	gateway := infratelegram.NewBotGateway(bot, logger)
 	downloader := infratelegram.NewTelegramFileDownloader(bot)
 	sessionStore := storage.NewRedisSessionStore(redisClient, cfg.Redis.TTLHours)
 	// n8n workflows (configure via env: N8N_WORKFLOW_<INTENT>=<url>)
 	workflows := map[string]n8n.WorkflowConfig{
 		"default": {
 			ID:         "default",
 			WebhookURL: cfg.N8n.BaseURL + "/webhook/default",
 			AuthToken:  cfg.N8n.AuthToken,
 		},
 	}
 	dispatcher := n8n.NewWebhookDispatcher(workflows, logger)
 	// Intent router with default rules
 	rules := []router.Rule{
 		{
 			Pattern:    regexp.MustCompile(`(?i)^/start`),
 			IntentName: "start",
 			Target:     entity.RouteTarget{Type: entity.RouteTargetBuiltin, WorkflowID: "start"},
 			Priority:   100,
 		},
 		{
 			Pattern:    regexp.MustCompile(`(?i)^/help`),
 			IntentName: "help",
 			Target:     entity.RouteTarget{Type: entity.RouteTargetBuiltin, WorkflowID: "help"},
 			Priority:   100,
 		},
 		{
 			Pattern:    regexp.MustCompile(`.*`),
 			IntentName: "general_query",
 			Target:     entity.RouteTarget{Type: entity.RouteTargetN8n, WorkflowID: "default"},
 			Priority:   0,
 		},
 	}
 	intentRouter := router.NewRuleBasedRouter(rules)
 	// Speech
 	transcriber := speech.NewOpenAIWhisper(cfg.Speech.OpenAIKey, cfg.Speech.WhisperModel, cfg.Speech.Language)
 	converter := speech.NewFFmpegConverter(cfg.Speech.FFmpegPath, "")
 	// Use cases
 	textUC := usecase.NewHandleTextMessage(intentRouter, dispatcher, sessionStore, gateway, logger)
 	voiceUC := usecase.NewHandleVoiceMessage(downloader, converter, transcriber, textUC, gateway, logger)
 	// Handler + poller
 	handler := interfaces.NewTelegramHandler(textUC, voiceUC, logger)
 	poller := infratelegram.NewUpdatePoller(bot, handler, logger)
 	logger.Info("starting bot", "mode", cfg.Bot.Mode)
 	if err := poller.Start(ctx); err != nil && err != context.Canceled {
 		logger.Error("poller stopped with error", "error", err)
 		os.Exit(1)
 	}
 	logger.Info("bot stopped gracefully")
 }
 func newLogger(cfg config.LogConfig) *slog.Logger {
 	var level slog.Level
 	switch cfg.Level {
 	case "debug":
 		level = slog.LevelDebug
 	case "warn":
 		level = slog.LevelWarn
 	case "error":
 		level = slog.LevelError
 	default:
 		level = slog.LevelInfo
 	}
 	opts := &slog.HandlerOptions{Level: level}
 	if cfg.Format == "text" {
 		return slog.New(slog.NewTextHandler(os.Stdout, opts))
 	}
 	return slog.New(slog.NewJSONHandler(os.Stdout, opts))
 }
--- a/deploy/Dockerfile
+++ b/deploy/Dockerfile
@@ -0,0 +1,15 @@
 # Stage 1: Build
 FROM golang:1.22-alpine AS builder
 WORKDIR /build
 COPY go.mod go.sum ./
 RUN go mod download
 COPY . .
 RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o /bot ./cmd/bot
 # Stage 2: Runtime
 FROM alpine:3.19
 RUN apk add --no-cache ffmpeg ca-certificates tzdata
 COPY --from=builder /bot /bot
 RUN adduser -D -u 1001 botuser
 USER botuser
 ENTRYPOINT ["/bot"]
--- a/deploy/docker-compose.yml
+++ b/deploy/docker-compose.yml
@@ -0,0 +1,31 @@
 services:
  bot:
    build:
      context: ..
      dockerfile: deploy/Dockerfile
    restart: unless-stopped
    environment:
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
      - N8N_BASE_URL=${N8N_BASE_URL}
      - N8N_AUTH_TOKEN=${N8N_AUTH_TOKEN}
      - REDIS_URL=redis://redis:6379
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - BOT_MODE=polling
      - LOG_LEVEL=info
    depends_on:
      redis:
        condition: service_healthy
  redis:
    image: redis:7-alpine
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
    volumes:
      - redis_data:/data
 volumes:
  redis_data:
--- a/go.mod
+++ b/go.mod
@@ -0,0 +1,19 @@
 module github.com/paramah/gw_telegram
 go 1.22
 require (
 	github.com/go-telegram-bot-api/telegram-bot-api/v5 v5.5.1
 	github.com/google/uuid v1.6.0
 	github.com/kelseyhightower/envconfig v1.4.0
 	github.com/redis/go-redis/v9 v9.5.1
 	github.com/stretchr/testify v1.9.0
 )
 require (
 	github.com/cespare/xxhash/v2 v2.2.0 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )
--- a/go.sum
+++ b/go.sum
@@ -0,0 +1,26 @@
 github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=
 github.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c=
 github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA=
 github.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0=
 github.com/cespare/xxhash/v2 v2.2.0 h1:DC2CZ1Ep5Y4k3ZQ899DldepgrayRUGE6BBZ/cd9Cj44=
 github.com/cespare/xxhash/v2 v2.2.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/rVNCu3HqELle0jiPLLBs70cWOduZpkS1E78=
 github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=
 github.com/go-telegram-bot-api/telegram-bot-api/v5 v5.5.1 h1:wG8n/XJQ07TmjbITcGiUaOtXxdrINDz1b0J1w0SzqDc=
 github.com/go-telegram-bot-api/telegram-bot-api/v5 v5.5.1/go.mod h1:A2S0CWkNylc2phvKXWBBdD3K0iGnDBGbzRpISP2zBl8=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/kelseyhightower/envconfig v1.4.0 h1:Im6hONhd3pLkfDFsbRgu68RDNkGF1r3dvMUtDTo2cv8=
 github.com/kelseyhightower/envconfig v1.4.0/go.mod h1:cccZRl6mQpaq41TPp5QxidR+Sa3axMbJDNb//FQX6Gg=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/redis/go-redis/v9 v9.5.1 h1:H1X4D3yHPaYrkL5X06Wh6xNVM/pX0Ft4RV0vMGvLBh8=
 github.com/redis/go-redis/v9 v9.5.1/go.mod h1:hdY0cQFCN4fnSYT6TkisLufl/4W5UIXyv0b/CLO2V2M=
 github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
 github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
--- a/internal/application/dto/incoming_message.go
+++ b/internal/application/dto/incoming_message.go
@@ -0,0 +1,17 @@
 package dto
 import "time"
 type IncomingMessageDTO struct {
 	MessageID   int64
 	ChatID      int64
 	UserID      int64
 	Username    string
 	FirstName   string
 	LastName    string
 	Text        string
 	VoiceFileID string
 	IsVoice     bool
 	Timestamp   time.Time
 	Language    string
 }
--- a/internal/application/dto/workflow_result.go
+++ b/internal/application/dto/workflow_result.go
@@ -0,0 +1,7 @@
 package dto
 type WorkflowResultDTO struct {
 	RequestID string
 	ReplyText string
 	Error     error
 }
--- a/internal/application/usecase/handle_text_message.go
+++ b/internal/application/usecase/handle_text_message.go
@@ -0,0 +1,115 @@
 package usecase
 import (
 	"context"
 	"fmt"
 	"log/slog"
 	"time"
 	"github.com/google/uuid"
 	"github.com/paramah/gw_telegram/internal/application/dto"
 	"github.com/paramah/gw_telegram/internal/domain/apperror"
 	"github.com/paramah/gw_telegram/internal/domain/entity"
 	"github.com/paramah/gw_telegram/internal/domain/port"
 )
 type HandleTextMessage struct {
 	router     port.IntentRouter
 	dispatcher port.WorkflowDispatcher
 	sessions   port.SessionStore
 	gateway    port.MessageGateway
 	logger     *slog.Logger
 }
 func NewHandleTextMessage(
 	router port.IntentRouter,
 	dispatcher port.WorkflowDispatcher,
 	sessions port.SessionStore,
 	gateway port.MessageGateway,
 	logger *slog.Logger,
 ) *HandleTextMessage {
 	return &HandleTextMessage{
 		router:     router,
 		dispatcher: dispatcher,
 		sessions:   sessions,
 		gateway:    gateway,
 		logger:     logger,
 	}
 }
 func (h *HandleTextMessage) Execute(ctx context.Context, in dto.IncomingMessageDTO) error {
 	if in.Text == "" {
 		return apperror.ErrMessageEmpty
 	}
 	msg := entity.Message{
 		MessageID: in.MessageID,
 		ChatID:    in.ChatID,
 		UserID:    in.UserID,
 		Username:  in.Username,
 		Type:      entity.MessageTypeText,
 		Text:      in.Text,
 		Timestamp: in.Timestamp,
 		Metadata:  map[string]any{"language": in.Language},
 	}
 	session, err := h.sessions.Get(ctx, in.UserID)
 	if err != nil {
 		h.logger.WarnContext(ctx, "session not found, using empty session", "user_id", in.UserID)
 		session = entity.Session{
 			UserID:    in.UserID,
 			ChatID:    in.ChatID,
 			Data:      make(map[string]any),
 			UpdatedAt: time.Now(),
 		}
 	}
 	route, err := h.router.Route(ctx, msg)
 	if err != nil {
 		h.logger.ErrorContext(ctx, "routing failed", "error", err, "user_id", in.UserID)
 		_ = h.gateway.SendText(ctx, in.ChatID, "Sorry, I couldn't process your message. Please try again.")
 		return fmt.Errorf("handle text message: route: %w", err)
 	}
 	session.History = append(session.History, msg)
 	if len(session.History) > 20 {
 		session.History = session.History[len(session.History)-20:]
 	}
 	req := entity.WorkflowRequest{
 		RequestID:   uuid.New().String(),
 		ChatID:      in.ChatID,
 		UserID:      in.UserID,
 		Username:    in.Username,
 		MessageText: in.Text,
 		Intent: entity.Intent{
 			Name: route.IntentName,
 		},
 		Session:   session,
 		Timestamp: in.Timestamp,
 		Metadata:  map[string]any{"route_target_type": string(route.Target.Type)},
 	}
 	_ = h.gateway.SendTyping(ctx, in.ChatID)
 	resp, err := h.dispatcher.Dispatch(ctx, req)
 	if err != nil {
 		h.logger.ErrorContext(ctx, "dispatch failed", "error", err, "request_id", req.RequestID)
 		_ = h.gateway.SendText(ctx, in.ChatID, "Sorry, the service is temporarily unavailable. Please try again later.")
 		return fmt.Errorf("handle text message: dispatch: %w", err)
 	}
 	if resp.ReplyText != "" {
 		if err := h.gateway.SendText(ctx, in.ChatID, resp.ReplyText); err != nil {
 			return fmt.Errorf("handle text message: send reply: %w", err)
 		}
 	}
 	session.CurrentWorkflow = route.Target.WorkflowID
 	session.UpdatedAt = time.Now()
 	if err := h.sessions.Set(ctx, session); err != nil {
 		h.logger.WarnContext(ctx, "failed to persist session", "error", err, "user_id", in.UserID)
 	}
 	return nil
 }
--- a/internal/application/usecase/handle_text_message_test.go
+++ b/internal/application/usecase/handle_text_message_test.go
@@ -0,0 +1,131 @@
 package usecase_test
 import (
 	"context"
 	"errors"
 	"log/slog"
 	"os"
 	"testing"
 	"time"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"github.com/paramah/gw_telegram/internal/application/dto"
 	"github.com/paramah/gw_telegram/internal/application/usecase"
 	"github.com/paramah/gw_telegram/internal/domain/apperror"
 	"github.com/paramah/gw_telegram/internal/domain/entity"
 	"github.com/paramah/gw_telegram/test/testutil"
 )
 func newTestLogger() *slog.Logger {
 	return slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelError}))
 }
 func validTextDTO() dto.IncomingMessageDTO {
 	return dto.IncomingMessageDTO{
 		MessageID: 1,
 		ChatID:    100,
 		UserID:    200,
 		Username:  "testuser",
 		Text:      "Hello, I need help",
 		Timestamp: time.Now(),
 		Language:  "en",
 	}
 }
 func TestHandleTextMessage_Execute_HappyPath(t *testing.T) {
 	router := &testutil.FakeIntentRouter{
 		RouteResult: entity.Route{
 			IntentName: "general_query",
 			Target: entity.RouteTarget{
 				Type:       entity.RouteTargetN8n,
 				WorkflowID: "general-webhook",
 			},
 		},
 	}
 	dispatcher := &testutil.FakeWorkflowDispatcher{
 		Response: entity.WorkflowResponse{
 			ReplyText: "Here is my response",
 		},
 	}
 	sessions := &testutil.FakeSessionStore{}
 	gateway := &testutil.FakeMessageGateway{}
 	uc := usecase.NewHandleTextMessage(router, dispatcher, sessions, gateway, newTestLogger())
 	err := uc.Execute(context.Background(), validTextDTO())
 	require.NoError(t, err)
 	assert.Equal(t, 1, dispatcher.CallCount)
 	assert.Equal(t, "Here is my response", gateway.LastSentText)
 	assert.Equal(t, int64(100), gateway.LastChatID)
 }
 func TestHandleTextMessage_Execute_EmptyText(t *testing.T) {
 	uc := usecase.NewHandleTextMessage(
 		&testutil.FakeIntentRouter{},
 		&testutil.FakeWorkflowDispatcher{},
 		&testutil.FakeSessionStore{},
 		&testutil.FakeMessageGateway{},
 		newTestLogger(),
 	)
 	in := validTextDTO()
 	in.Text = ""
 	err := uc.Execute(context.Background(), in)
 	assert.ErrorIs(t, err, apperror.ErrMessageEmpty)
 }
 func TestHandleTextMessage_Execute_RouteNotFound(t *testing.T) {
 	router := &testutil.FakeIntentRouter{Error: apperror.ErrRouteNotFound}
 	dispatcher := &testutil.FakeWorkflowDispatcher{}
 	sessions := &testutil.FakeSessionStore{}
 	gateway := &testutil.FakeMessageGateway{}
 	uc := usecase.NewHandleTextMessage(router, dispatcher, sessions, gateway, newTestLogger())
 	err := uc.Execute(context.Background(), validTextDTO())
 	assert.Error(t, err)
 	assert.True(t, errors.Is(err, apperror.ErrRouteNotFound))
 	assert.Equal(t, 0, dispatcher.CallCount)
 	assert.NotEmpty(t, gateway.LastSentText) // error message sent to user
 }
 func TestHandleTextMessage_Execute_DispatchError(t *testing.T) {
 	router := &testutil.FakeIntentRouter{
 		RouteResult: entity.Route{IntentName: "general_query"},
 	}
 	dispatcher := &testutil.FakeWorkflowDispatcher{
 		Error: errors.New("n8n unavailable"),
 	}
 	sessions := &testutil.FakeSessionStore{}
 	gateway := &testutil.FakeMessageGateway{}
 	uc := usecase.NewHandleTextMessage(router, dispatcher, sessions, gateway, newTestLogger())
 	err := uc.Execute(context.Background(), validTextDTO())
 	assert.Error(t, err)
 	assert.Equal(t, 1, dispatcher.CallCount)
 	assert.NotEmpty(t, gateway.LastSentText) // fallback error message sent to user
 }
 func TestHandleTextMessage_Execute_SessionPersisted(t *testing.T) {
 	router := &testutil.FakeIntentRouter{
 		RouteResult: entity.Route{
 			IntentName: "general_query",
 			Target:     entity.RouteTarget{WorkflowID: "wf-1"},
 		},
 	}
 	dispatcher := &testutil.FakeWorkflowDispatcher{
 		Response: entity.WorkflowResponse{ReplyText: "OK"},
 	}
 	sessions := &testutil.FakeSessionStore{}
 	gateway := &testutil.FakeMessageGateway{}
 	uc := usecase.NewHandleTextMessage(router, dispatcher, sessions, gateway, newTestLogger())
 	err := uc.Execute(context.Background(), validTextDTO())
 	require.NoError(t, err)
 	assert.True(t, sessions.SetCalled)
 	assert.Equal(t, "wf-1", sessions.LastSetSession.CurrentWorkflow)
 }
--- a/internal/application/usecase/handle_voice_message.go
+++ b/internal/application/usecase/handle_voice_message.go
@@ -0,0 +1,80 @@
 package usecase
 import (
 	"context"
 	"fmt"
 	"log/slog"
 	"github.com/paramah/gw_telegram/internal/application/dto"
 	"github.com/paramah/gw_telegram/internal/domain/port"
 )
 type HandleVoiceMessage struct {
 	downloader  port.FileDownloader
 	converter   AudioConverter
 	transcriber port.SpeechTranscriber
 	textHandler *HandleTextMessage
 	gateway     port.MessageGateway
 	logger      *slog.Logger
 }
 // AudioConverter converts audio between formats (OGG -> WAV etc.)
 type AudioConverter interface {
 	Convert(ctx context.Context, input []byte, fromMime, toMime string) ([]byte, error)
 }
 func NewHandleVoiceMessage(
 	downloader port.FileDownloader,
 	converter AudioConverter,
 	transcriber port.SpeechTranscriber,
 	textHandler *HandleTextMessage,
 	gateway port.MessageGateway,
 	logger *slog.Logger,
 ) *HandleVoiceMessage {
 	return &HandleVoiceMessage{
 		downloader:  downloader,
 		converter:   converter,
 		transcriber: transcriber,
 		textHandler: textHandler,
 		gateway:     gateway,
 		logger:      logger,
 	}
 }
 func (h *HandleVoiceMessage) Execute(ctx context.Context, in dto.IncomingMessageDTO) error {
 	_ = h.gateway.SendTyping(ctx, in.ChatID)
 	audioBytes, mimeType, err := h.downloader.Download(ctx, in.VoiceFileID)
 	if err != nil {
 		h.logger.ErrorContext(ctx, "voice download failed", "error", err, "file_id", in.VoiceFileID)
 		_ = h.gateway.SendText(ctx, in.ChatID, "Sorry, I couldn't download the audio message. Please try again.")
 		return fmt.Errorf("handle voice: download: %w", err)
 	}
 	// Convert OGG Opus (Telegram default) to WAV for Whisper
 	if mimeType == "audio/ogg" || mimeType == "" {
 		wavBytes, err := h.converter.Convert(ctx, audioBytes, "audio/ogg", "audio/wav")
 		if err != nil {
 			h.logger.WarnContext(ctx, "audio conversion failed, trying raw", "error", err)
 			// fall through with original bytes
 		} else {
 			audioBytes = wavBytes
 			mimeType = "audio/wav"
 		}
 	}
 	transcript, err := h.transcriber.Transcribe(ctx, audioBytes, mimeType)
 	if err != nil {
 		h.logger.ErrorContext(ctx, "transcription failed", "error", err)
 		_ = h.gateway.SendText(ctx, in.ChatID, "Sorry, I couldn't understand the voice message. Please try sending text instead.")
 		return fmt.Errorf("handle voice: transcribe: %w", err)
 	}
 	h.logger.InfoContext(ctx, "voice transcribed", "user_id", in.UserID, "length", len(transcript))
 	textIn := in
 	textIn.Text = transcript
 	textIn.IsVoice = false
 	return h.textHandler.Execute(ctx, textIn)
 }
--- a/internal/application/usecase/handle_voice_message_test.go
+++ b/internal/application/usecase/handle_voice_message_test.go
@@ -0,0 +1,99 @@
 package usecase_test
 import (
 	"context"
 	"errors"
 	"testing"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"github.com/paramah/gw_telegram/internal/application/dto"
 	"github.com/paramah/gw_telegram/internal/application/usecase"
 	"github.com/paramah/gw_telegram/internal/domain/entity"
 	"github.com/paramah/gw_telegram/test/testutil"
 )
 func validVoiceDTO() dto.IncomingMessageDTO {
 	return dto.IncomingMessageDTO{
 		MessageID:   2,
 		ChatID:      100,
 		UserID:      200,
 		Username:    "testuser",
 		VoiceFileID: "file_abc123",
 		IsVoice:     true,
 	}
 }
 func TestHandleVoiceMessage_Execute_HappyPath(t *testing.T) {
 	downloader := &testutil.FakeFileDownloader{
 		Data:     []byte("fake-ogg-audio"),
 		MimeType: "audio/ogg",
 	}
 	converter := &testutil.FakeAudioConverter{Output: []byte("fake-wav-audio")}
 	transcriber := &testutil.FakeSpeechTranscriber{Transcript: "I need help with my order"}
 	router := &testutil.FakeIntentRouter{
 		RouteResult: entity.Route{IntentName: "order_inquiry"},
 	}
 	dispatcher := &testutil.FakeWorkflowDispatcher{
 		Response: entity.WorkflowResponse{ReplyText: "Order status: shipped"},
 	}
 	sessions := &testutil.FakeSessionStore{}
 	gateway := &testutil.FakeMessageGateway{}
 	textUC := usecase.NewHandleTextMessage(router, dispatcher, sessions, gateway, newTestLogger())
 	uc := usecase.NewHandleVoiceMessage(downloader, converter, transcriber, textUC, gateway, newTestLogger())
 	err := uc.Execute(context.Background(), validVoiceDTO())
 	require.NoError(t, err)
 	assert.Equal(t, 1, transcriber.CallCount)
 	assert.Equal(t, 1, dispatcher.CallCount)
 	assert.Equal(t, "I need help with my order", dispatcher.LastRequest.MessageText)
 	assert.Equal(t, "Order status: shipped", gateway.LastSentText)
 }
 func TestHandleVoiceMessage_Execute_DownloadFails(t *testing.T) {
 	downloader := &testutil.FakeFileDownloader{Error: errors.New("download error")}
 	transcriber := &testutil.FakeSpeechTranscriber{}
 	gateway := &testutil.FakeMessageGateway{}
 	textUC := usecase.NewHandleTextMessage(
 		&testutil.FakeIntentRouter{},
 		&testutil.FakeWorkflowDispatcher{},
 		&testutil.FakeSessionStore{},
 		gateway,
 		newTestLogger(),
 	)
 	uc := usecase.NewHandleVoiceMessage(downloader, &testutil.FakeAudioConverter{}, transcriber, textUC, gateway, newTestLogger())
 	err := uc.Execute(context.Background(), validVoiceDTO())
 	assert.Error(t, err)
 	assert.Equal(t, 0, transcriber.CallCount)
 	assert.NotEmpty(t, gateway.LastSentText) // error message sent
 }
 func TestHandleVoiceMessage_Execute_TranscriptionFails(t *testing.T) {
 	downloader := &testutil.FakeFileDownloader{
 		Data:     []byte("audio"),
 		MimeType: "audio/ogg",
 	}
 	transcriber := &testutil.FakeSpeechTranscriber{Error: errors.New("whisper error")}
 	gateway := &testutil.FakeMessageGateway{}
 	dispatcher := &testutil.FakeWorkflowDispatcher{}
 	textUC := usecase.NewHandleTextMessage(
 		&testutil.FakeIntentRouter{},
 		dispatcher,
 		&testutil.FakeSessionStore{},
 		gateway,
 		newTestLogger(),
 	)
 	uc := usecase.NewHandleVoiceMessage(downloader, &testutil.FakeAudioConverter{}, transcriber, textUC, gateway, newTestLogger())
 	err := uc.Execute(context.Background(), validVoiceDTO())
 	assert.Error(t, err)
 	assert.Equal(t, 0, dispatcher.CallCount)
 	assert.NotEmpty(t, gateway.LastSentText)
 }
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -0,0 +1,69 @@
 package config
 import (
 	"fmt"
 	"os"
 	"github.com/kelseyhightower/envconfig"
 )
 type Config struct {
 	Bot    BotConfig
 	N8n    N8nConfig
 	Speech SpeechConfig
 	Redis  RedisConfig
 	Server ServerConfig
 	Log    LogConfig
 }
 type BotConfig struct {
 	Token      string `envconfig:"TELEGRAM_BOT_TOKEN" required:"true"`
 	Mode       string `envconfig:"BOT_MODE"           default:"polling"`
 	WebhookURL string `envconfig:"TELEGRAM_WEBHOOK_URL"`
 	Debug      bool   `envconfig:"TELEGRAM_DEBUG"     default:"false"`
 }
 type N8nConfig struct {
 	BaseURL     string `envconfig:"N8N_BASE_URL"    required:"true"`
 	AuthToken   string `envconfig:"N8N_AUTH_TOKEN"`
 	TimeoutSecs int    `envconfig:"N8N_TIMEOUT"     default:"30"`
 	RetryCount  int    `envconfig:"N8N_RETRY_COUNT" default:"3"`
 }
 type SpeechConfig struct {
 	Provider     string `envconfig:"STT_PROVIDER"     default:"openai"`
 	OpenAIKey    string `envconfig:"OPENAI_API_KEY"`
 	WhisperModel string `envconfig:"WHISPER_MODEL"    default:"whisper-1"`
 	Language     string `envconfig:"WHISPER_LANGUAGE" default:""`
 	FFmpegPath   string `envconfig:"FFMPEG_PATH"      default:"ffmpeg"`
 }
 type RedisConfig struct {
 	URL      string `envconfig:"REDIS_URL"   default:"redis://localhost:6379"`
 	TTLHours int    `envconfig:"SESSION_TTL" default:"24"`
 }
 type ServerConfig struct {
 	Port int `envconfig:"SERVER_PORT" default:"8080"`
 }
 type LogConfig struct {
 	Level  string `envconfig:"LOG_LEVEL"  default:"info"`
 	Format string `envconfig:"LOG_FORMAT" default:"json"`
 }
 func Load() (*Config, error) {
 	var cfg Config
 	if err := envconfig.Process("", &cfg); err != nil {
 		return nil, fmt.Errorf("load config: %w", err)
 	}
 	return &cfg, nil
 }
 func MustLoad() *Config {
 	cfg, err := Load()
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "fatal: %v\n", err)
 		os.Exit(1)
 	}
 	return cfg
 }
--- a/internal/domain/apperror/errors.go
+++ b/internal/domain/apperror/errors.go
@@ -0,0 +1,25 @@
 package apperror
 import "errors"
 type AppError struct {
 	Code    string
 	Message string
 }
 func (e *AppError) Error() string {
 	return e.Message
 }
 var (
 	ErrMessageEmpty        = &AppError{Code: "MSG_EMPTY", Message: "message text is empty"}
 	ErrRouteNotFound       = &AppError{Code: "ROUTE_NOT_FOUND", Message: "no route found for message"}
 	ErrWorkflowTimeout     = &AppError{Code: "WORKFLOW_TIMEOUT", Message: "workflow call timed out"}
 	ErrTranscriptionFailed = &AppError{Code: "TRANSCRIPTION_FAILED", Message: "voice transcription failed"}
 	ErrSessionNotFound     = &AppError{Code: "SESSION_NOT_FOUND", Message: "session not found"}
 	ErrDownloadFailed      = &AppError{Code: "DOWNLOAD_FAILED", Message: "file download failed"}
 )
 func Is(err, target error) bool {
 	return errors.Is(err, target)
 }
--- a/internal/domain/entity/intent.go
+++ b/internal/domain/entity/intent.go
@@ -0,0 +1,28 @@
 package entity
 type Intent struct {
 	Name       string
 	Confidence float64
 	Entities   map[string]any
 }
 type RouteTargetType string
 const (
 	RouteTargetN8n     RouteTargetType = "n8n"
 	RouteTargetAIAgent RouteTargetType = "ai_agent"
 	RouteTargetBuiltin RouteTargetType = "builtin"
 )
 type RouteTarget struct {
 	Type       RouteTargetType
 	WorkflowID string
 	Endpoint   string
 }
 type Route struct {
 	Pattern    string
 	IntentName string
 	Target     RouteTarget
 	Priority   int
 }
--- a/internal/domain/entity/message.go
+++ b/internal/domain/entity/message.go
@@ -0,0 +1,29 @@
 package entity
 import "time"
 type MessageType string
 const (
 	MessageTypeText  MessageType = "text"
 	MessageTypeVoice MessageType = "voice"
 )
 type Message struct {
 	MessageID   int64
 	ChatID      int64
 	UserID      int64
 	Username    string
 	Type        MessageType
 	Text        string
 	VoiceFileID string
 	Timestamp   time.Time
 	Metadata    map[string]any
 }
 type VoiceMessage struct {
 	FileID   string
 	Duration int
 	MimeType string
 	FileSize int
 }
--- a/internal/domain/entity/user.go
+++ b/internal/domain/entity/user.go
@@ -0,0 +1,22 @@
 package entity
 import "time"
 type User struct {
 	TelegramID int64
 	Username   string
 	FirstName  string
 	LastName   string
 	Language   string
 	CreatedAt  time.Time
 }
 type Session struct {
 	UserID          int64
 	ChatID          int64
 	CurrentWorkflow string
 	History         []Message
 	Data            map[string]any
 	UpdatedAt       time.Time
 	TTL             int // hours
 }
--- a/internal/domain/entity/workflow.go
+++ b/internal/domain/entity/workflow.go
@@ -0,0 +1,29 @@
 package entity
 import "time"
 type WorkflowRequest struct {
 	RequestID   string
 	ChatID      int64
 	UserID      int64
 	Username    string
 	MessageText string
 	Intent      Intent
 	Session     Session
 	Timestamp   time.Time
 	Metadata    map[string]any
 }
 type Action struct {
 	Type  string
 	Key   string
 	Value any
 }
 type WorkflowResponse struct {
 	RequestID    string
 	ReplyText    string
 	Actions      []Action
 	NextWorkflow string
 	Error        error
 }
--- a/internal/domain/port/file_downloader.go
+++ b/internal/domain/port/file_downloader.go
@@ -0,0 +1,7 @@
 package port
 import "context"
 type FileDownloader interface {
 	Download(ctx context.Context, fileID string) ([]byte, string, error) // bytes, mimeType, error
 }
--- a/internal/domain/port/intent_router.go
+++ b/internal/domain/port/intent_router.go
@@ -0,0 +1,10 @@
 package port
 import (
 	"context"
 	"github.com/paramah/gw_telegram/internal/domain/entity"
 )
 type IntentRouter interface {
 	Route(ctx context.Context, msg entity.Message) (entity.Route, error)
 }
--- a/internal/domain/port/message_gateway.go
+++ b/internal/domain/port/message_gateway.go
@@ -0,0 +1,8 @@
 package port
 import "context"
 type MessageGateway interface {
 	SendText(ctx context.Context, chatID int64, text string) error
 	SendTyping(ctx context.Context, chatID int64) error
 }
--- a/internal/domain/port/session_store.go
+++ b/internal/domain/port/session_store.go
@@ -0,0 +1,12 @@
 package port
 import (
 	"context"
 	"github.com/paramah/gw_telegram/internal/domain/entity"
 )
 type SessionStore interface {
 	Get(ctx context.Context, userID int64) (entity.Session, error)
 	Set(ctx context.Context, session entity.Session) error
 	Delete(ctx context.Context, userID int64) error
 }
--- a/internal/domain/port/speech_transcriber.go
+++ b/internal/domain/port/speech_transcriber.go
@@ -0,0 +1,7 @@
 package port
 import "context"
 type SpeechTranscriber interface {
 	Transcribe(ctx context.Context, audioData []byte, mimeType string) (string, error)
 }
--- a/internal/domain/port/workflow_dispatcher.go
+++ b/internal/domain/port/workflow_dispatcher.go
@@ -0,0 +1,10 @@
 package port
 import (
 	"context"
 	"github.com/paramah/gw_telegram/internal/domain/entity"
 )
 type WorkflowDispatcher interface {
 	Dispatch(ctx context.Context, req entity.WorkflowRequest) (entity.WorkflowResponse, error)
 }
--- a/internal/infrastructure/n8n/payload.go
+++ b/internal/infrastructure/n8n/payload.go
@@ -0,0 +1,8 @@
 package n8n
 // payload.go contains shared payload types for n8n webhook communication.
 // The primary types (n8nPayload, n8nResponse) are defined in webhook_dispatcher.go
 // to keep them co-located with their usage.
 //
 // This file is reserved for any additional payload structures needed
 // for extended n8n integration (e.g., batch requests, webhook registration).
--- a/internal/infrastructure/n8n/webhook_dispatcher.go
+++ b/internal/infrastructure/n8n/webhook_dispatcher.go
@@ -0,0 +1,124 @@
 package n8n
 import (
 	"bytes"
 	"context"
 	"encoding/json"
 	"fmt"
 	"io"
 	"log/slog"
 	"net/http"
 	"time"
 	"github.com/paramah/gw_telegram/internal/domain/entity"
 )
 type WorkflowConfig struct {
 	ID         string
 	WebhookURL string
 	AuthToken  string
 	Timeout    time.Duration
 }
 type WebhookDispatcher struct {
 	workflows map[string]WorkflowConfig
 	client    *http.Client
 	logger    *slog.Logger
 }
 func NewWebhookDispatcher(workflows map[string]WorkflowConfig, logger *slog.Logger) *WebhookDispatcher {
 	return &WebhookDispatcher{
 		workflows: workflows,
 		client:    &http.Client{Timeout: 30 * time.Second},
 		logger:    logger,
 	}
 }
 type n8nPayload struct {
 	RequestID   string         `json:"request_id"`
 	ChatID      int64          `json:"chat_id"`
 	UserID      int64          `json:"user_id"`
 	Username    string         `json:"username"`
 	MessageText string         `json:"message_text"`
 	IntentName  string         `json:"intent_name"`
 	Timestamp   time.Time      `json:"timestamp"`
 	Metadata    map[string]any `json:"metadata,omitempty"`
 }
 type n8nResponse struct {
 	Reply        string          `json:"reply"`
 	Actions      []entity.Action `json:"actions,omitempty"`
 	NextWorkflow string          `json:"next_workflow,omitempty"`
 }
 func (d *WebhookDispatcher) Dispatch(ctx context.Context, req entity.WorkflowRequest) (entity.WorkflowResponse, error) {
 	wf, ok := d.workflows[req.Intent.Name]
 	if !ok {
 		// Try default workflow
 		wf, ok = d.workflows["default"]
 		if !ok {
 			return entity.WorkflowResponse{}, fmt.Errorf("no workflow configured for intent %q", req.Intent.Name)
 		}
 	}
 	payload := n8nPayload{
 		RequestID:   req.RequestID,
 		ChatID:      req.ChatID,
 		UserID:      req.UserID,
 		Username:    req.Username,
 		MessageText: req.MessageText,
 		IntentName:  req.Intent.Name,
 		Timestamp:   req.Timestamp,
 		Metadata:    req.Metadata,
 	}
 	body, err := json.Marshal(payload)
 	if err != nil {
 		return entity.WorkflowResponse{}, fmt.Errorf("marshal payload: %w", err)
 	}
 	httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, wf.WebhookURL, bytes.NewReader(body))
 	if err != nil {
 		return entity.WorkflowResponse{}, fmt.Errorf("create request: %w", err)
 	}
 	httpReq.Header.Set("Content-Type", "application/json")
 	if wf.AuthToken != "" {
 		httpReq.Header.Set("Authorization", "Bearer "+wf.AuthToken)
 	}
 	client := d.client
 	if wf.Timeout > 0 {
 		client = &http.Client{Timeout: wf.Timeout}
 	}
 	resp, err := client.Do(httpReq)
 	if err != nil {
 		return entity.WorkflowResponse{}, fmt.Errorf("n8n webhook call: %w", err)
 	}
 	defer resp.Body.Close()
 	respBody, err := io.ReadAll(resp.Body)
 	if err != nil {
 		return entity.WorkflowResponse{}, fmt.Errorf("read response: %w", err)
 	}
 	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
 		return entity.WorkflowResponse{}, fmt.Errorf("n8n returned status %d: %s", resp.StatusCode, string(respBody))
 	}
 	var n8nResp n8nResponse
 	if err := json.Unmarshal(respBody, &n8nResp); err != nil {
 		// If not valid JSON, treat the raw body as reply text
 		return entity.WorkflowResponse{
 			RequestID: req.RequestID,
 			ReplyText: string(respBody),
 		}, nil
 	}
 	return entity.WorkflowResponse{
 		RequestID:    req.RequestID,
 		ReplyText:    n8nResp.Reply,
 		Actions:      n8nResp.Actions,
 		NextWorkflow: n8nResp.NextWorkflow,
 	}, nil
 }
--- a/internal/infrastructure/router/rule_based_router.go
+++ b/internal/infrastructure/router/rule_based_router.go
@@ -0,0 +1,44 @@
 package router
 import (
 	"context"
 	"regexp"
 	"sort"
 	"github.com/paramah/gw_telegram/internal/domain/apperror"
 	"github.com/paramah/gw_telegram/internal/domain/entity"
 )
 type Rule struct {
 	Pattern    *regexp.Regexp
 	IntentName string
 	Target     entity.RouteTarget
 	Priority   int
 }
 type RuleBasedRouter struct {
 	rules []Rule
 }
 func NewRuleBasedRouter(rules []Rule) *RuleBasedRouter {
 	sorted := make([]Rule, len(rules))
 	copy(sorted, rules)
 	sort.Slice(sorted, func(i, j int) bool {
 		return sorted[i].Priority > sorted[j].Priority
 	})
 	return &RuleBasedRouter{rules: sorted}
 }
 func (r *RuleBasedRouter) Route(_ context.Context, msg entity.Message) (entity.Route, error) {
 	for _, rule := range r.rules {
 		if rule.Pattern.MatchString(msg.Text) {
 			return entity.Route{
 				Pattern:    rule.Pattern.String(),
 				IntentName: rule.IntentName,
 				Target:     rule.Target,
 				Priority:   rule.Priority,
 			}, nil
 		}
 	}
 	return entity.Route{}, apperror.ErrRouteNotFound
 }
--- a/internal/infrastructure/speech/audio_converter.go
+++ b/internal/infrastructure/speech/audio_converter.go
@@ -0,0 +1,63 @@
 package speech
 import (
 	"bytes"
 	"context"
 	"fmt"
 	"os"
 	"os/exec"
 	"path/filepath"
 	"github.com/google/uuid"
 )
 type FFmpegConverter struct {
 	ffmpegPath string
 	tempDir    string
 }
 func NewFFmpegConverter(ffmpegPath, tempDir string) *FFmpegConverter {
 	if ffmpegPath == "" {
 		ffmpegPath = "ffmpeg"
 	}
 	if tempDir == "" {
 		tempDir = os.TempDir()
 	}
 	return &FFmpegConverter{ffmpegPath: ffmpegPath, tempDir: tempDir}
 }
 func (c *FFmpegConverter) Convert(ctx context.Context, input []byte, fromMime, toMime string) ([]byte, error) {
 	id := uuid.New().String()
 	inFile := filepath.Join(c.tempDir, id+".input")
 	outFile := filepath.Join(c.tempDir, id+".wav")
 	defer os.Remove(inFile)
 	defer os.Remove(outFile)
 	if err := os.WriteFile(inFile, input, 0600); err != nil {
 		return nil, fmt.Errorf("write temp input: %w", err)
 	}
 	cmd := exec.CommandContext(ctx, c.ffmpegPath,
 		"-i", inFile,
 		"-ar", "16000",
 		"-ac", "1",
 		"-f", "wav",
 		"-y",
 		outFile,
 	)
 	var stderr bytes.Buffer
 	cmd.Stderr = &stderr
 	if err := cmd.Run(); err != nil {
 		return nil, fmt.Errorf("ffmpeg conversion: %w: %s", err, stderr.String())
 	}
 	out, err := os.ReadFile(outFile)
 	if err != nil {
 		return nil, fmt.Errorf("read converted file: %w", err)
 	}
 	return out, nil
 }
--- a/internal/infrastructure/speech/openai_whisper.go
+++ b/internal/infrastructure/speech/openai_whisper.go
@@ -0,0 +1,89 @@
 package speech
 import (
 	"bytes"
 	"context"
 	"encoding/json"
 	"fmt"
 	"io"
 	"mime/multipart"
 	"net/http"
 	"time"
 )
 const whisperAPIURL = "https://api.openai.com/v1/audio/transcriptions"
 type OpenAIWhisper struct {
 	apiKey   string
 	model    string
 	language string
 	client   *http.Client
 }
 func NewOpenAIWhisper(apiKey, model, language string) *OpenAIWhisper {
 	return &OpenAIWhisper{
 		apiKey:   apiKey,
 		model:    model,
 		language: language,
 		client:   &http.Client{Timeout: 60 * time.Second},
 	}
 }
 type whisperResponse struct {
 	Text string `json:"text"`
 }
 func (w *OpenAIWhisper) Transcribe(ctx context.Context, audioData []byte, mimeType string) (string, error) {
 	var buf bytes.Buffer
 	mw := multipart.NewWriter(&buf)
 	fw, err := mw.CreateFormFile("file", "audio.wav")
 	if err != nil {
 		return "", fmt.Errorf("create form file: %w", err)
 	}
 	if _, err := fw.Write(audioData); err != nil {
 		return "", fmt.Errorf("write audio data: %w", err)
 	}
 	if err := mw.WriteField("model", w.model); err != nil {
 		return "", fmt.Errorf("write model field: %w", err)
 	}
 	if err := mw.WriteField("response_format", "json"); err != nil {
 		return "", fmt.Errorf("write response_format: %w", err)
 	}
 	if w.language != "" {
 		if err := mw.WriteField("language", w.language); err != nil {
 			return "", fmt.Errorf("write language field: %w", err)
 		}
 	}
 	mw.Close()
 	req, err := http.NewRequestWithContext(ctx, http.MethodPost, whisperAPIURL, &buf)
 	if err != nil {
 		return "", fmt.Errorf("create whisper request: %w", err)
 	}
 	req.Header.Set("Authorization", "Bearer "+w.apiKey)
 	req.Header.Set("Content-Type", mw.FormDataContentType())
 	resp, err := w.client.Do(req)
 	if err != nil {
 		return "", fmt.Errorf("whisper API call: %w", err)
 	}
 	defer resp.Body.Close()
 	body, err := io.ReadAll(resp.Body)
 	if err != nil {
 		return "", fmt.Errorf("read whisper response: %w", err)
 	}
 	if resp.StatusCode != http.StatusOK {
 		return "", fmt.Errorf("whisper API error %d: %s", resp.StatusCode, string(body))
 	}
 	var result whisperResponse
 	if err := json.Unmarshal(body, &result); err != nil {
 		return "", fmt.Errorf("parse whisper response: %w", err)
 	}
 	return result.Text, nil
 }
--- a/internal/infrastructure/storage/redis_session_store.go
+++ b/internal/infrastructure/storage/redis_session_store.go
@@ -0,0 +1,62 @@
 package storage
 import (
 	"context"
 	"encoding/json"
 	"fmt"
 	"time"
 	"github.com/redis/go-redis/v9"
 	"github.com/paramah/gw_telegram/internal/domain/apperror"
 	"github.com/paramah/gw_telegram/internal/domain/entity"
 )
 type RedisSessionStore struct {
 	client *redis.Client
 	ttl    time.Duration
 }
 func NewRedisSessionStore(client *redis.Client, ttlHours int) *RedisSessionStore {
 	return &RedisSessionStore{
 		client: client,
 		ttl:    time.Duration(ttlHours) * time.Hour,
 	}
 }
 func sessionKey(userID int64) string {
 	return fmt.Sprintf("session:%d", userID)
 }
 func (s *RedisSessionStore) Get(ctx context.Context, userID int64) (entity.Session, error) {
 	data, err := s.client.Get(ctx, sessionKey(userID)).Bytes()
 	if err == redis.Nil {
 		return entity.Session{}, apperror.ErrSessionNotFound
 	}
 	if err != nil {
 		return entity.Session{}, fmt.Errorf("redis get session: %w", err)
 	}
 	var session entity.Session
 	if err := json.Unmarshal(data, &session); err != nil {
 		return entity.Session{}, fmt.Errorf("unmarshal session: %w", err)
 	}
 	return session, nil
 }
 func (s *RedisSessionStore) Set(ctx context.Context, session entity.Session) error {
 	data, err := json.Marshal(session)
 	if err != nil {
 		return fmt.Errorf("marshal session: %w", err)
 	}
 	if err := s.client.Set(ctx, sessionKey(session.UserID), data, s.ttl).Err(); err != nil {
 		return fmt.Errorf("redis set session: %w", err)
 	}
 	return nil
 }
 func (s *RedisSessionStore) Delete(ctx context.Context, userID int64) error {
 	if err := s.client.Del(ctx, sessionKey(userID)).Err(); err != nil {
 		return fmt.Errorf("redis del session: %w", err)
 	}
 	return nil
 }
--- a/internal/infrastructure/telegram/bot_gateway.go
+++ b/internal/infrastructure/telegram/bot_gateway.go
@@ -0,0 +1,37 @@
 package telegram
 import (
 	"context"
 	"fmt"
 	"log/slog"
 	tgbotapi "github.com/go-telegram-bot-api/telegram-bot-api/v5"
 )
 type BotGateway struct {
 	bot    *tgbotapi.BotAPI
 	logger *slog.Logger
 }
 func NewBotGateway(bot *tgbotapi.BotAPI, logger *slog.Logger) *BotGateway {
 	return &BotGateway{bot: bot, logger: logger}
 }
 func (g *BotGateway) SendText(ctx context.Context, chatID int64, text string) error {
 	msg := tgbotapi.NewMessage(chatID, text)
 	msg.ParseMode = tgbotapi.ModeMarkdown
 	_, err := g.bot.Send(msg)
 	if err != nil {
 		return fmt.Errorf("telegram send text: %w", err)
 	}
 	return nil
 }
 func (g *BotGateway) SendTyping(ctx context.Context, chatID int64) error {
 	action := tgbotapi.NewChatAction(chatID, tgbotapi.ChatTyping)
 	_, err := g.bot.Request(action)
 	if err != nil {
 		g.logger.WarnContext(ctx, "failed to send typing action", "error", err, "chat_id", chatID)
 	}
 	return nil
 }
--- a/internal/infrastructure/telegram/file_downloader.go
+++ b/internal/infrastructure/telegram/file_downloader.go
@@ -0,0 +1,48 @@
 package telegram
 import (
 	"context"
 	"fmt"
 	"io"
 	"net/http"
 	tgbotapi "github.com/go-telegram-bot-api/telegram-bot-api/v5"
 )
 type TelegramFileDownloader struct {
 	bot    *tgbotapi.BotAPI
 	client *http.Client
 }
 func NewTelegramFileDownloader(bot *tgbotapi.BotAPI) *TelegramFileDownloader {
 	return &TelegramFileDownloader{
 		bot:    bot,
 		client: &http.Client{},
 	}
 }
 func (d *TelegramFileDownloader) Download(ctx context.Context, fileID string) ([]byte, string, error) {
 	file, err := d.bot.GetFile(tgbotapi.FileConfig{FileID: fileID})
 	if err != nil {
 		return nil, "", fmt.Errorf("get file info: %w", err)
 	}
 	url := file.Link(d.bot.Token)
 	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
 	if err != nil {
 		return nil, "", fmt.Errorf("create download request: %w", err)
 	}
 	resp, err := d.client.Do(req)
 	if err != nil {
 		return nil, "", fmt.Errorf("download file: %w", err)
 	}
 	defer resp.Body.Close()
 	data, err := io.ReadAll(resp.Body)
 	if err != nil {
 		return nil, "", fmt.Errorf("read file body: %w", err)
 	}
 	return data, "audio/ogg", nil
 }
--- a/internal/infrastructure/telegram/update_poller.go
+++ b/internal/infrastructure/telegram/update_poller.go
@@ -0,0 +1,50 @@
 package telegram
 import (
 	"context"
 	"log/slog"
 	tgbotapi "github.com/go-telegram-bot-api/telegram-bot-api/v5"
 )
 type UpdateHandler interface {
 	Handle(ctx context.Context, update tgbotapi.Update)
 }
 type UpdatePoller struct {
 	bot     *tgbotapi.BotAPI
 	handler UpdateHandler
 	logger  *slog.Logger
 	timeout int
 }
 func NewUpdatePoller(bot *tgbotapi.BotAPI, handler UpdateHandler, logger *slog.Logger) *UpdatePoller {
 	return &UpdatePoller{
 		bot:     bot,
 		handler: handler,
 		logger:  logger,
 		timeout: 60,
 	}
 }
 func (p *UpdatePoller) Start(ctx context.Context) error {
 	u := tgbotapi.NewUpdate(0)
 	u.Timeout = p.timeout
 	updates := p.bot.GetUpdatesChan(u)
 	p.logger.InfoContext(ctx, "update poller started")
 	for {
 		select {
 		case <-ctx.Done():
 			p.bot.StopReceivingUpdates()
 			p.logger.InfoContext(ctx, "update poller stopped")
 			return ctx.Err()
 		case update, ok := <-updates:
 			if !ok {
 				return nil
 			}
 			go p.handler.Handle(ctx, update)
 		}
 	}
 }
--- a/internal/interfaces/health_handler.go
+++ b/internal/interfaces/health_handler.go
@@ -0,0 +1,27 @@
 package interfaces
 import (
 	"encoding/json"
 	"net/http"
 	"time"
 )
 type HealthHandler struct{}
 func NewHealthHandler() *HealthHandler {
 	return &HealthHandler{}
 }
 type healthResponse struct {
 	Status    string    `json:"status"`
 	Timestamp time.Time `json:"timestamp"`
 }
 func (h *HealthHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(http.StatusOK)
 	_ = json.NewEncoder(w).Encode(healthResponse{
 		Status:    "ok",
 		Timestamp: time.Now().UTC(),
 	})
 }
--- a/internal/interfaces/telegram_handler.go
+++ b/internal/interfaces/telegram_handler.go
@@ -0,0 +1,74 @@
 package interfaces
 import (
 	"context"
 	"log/slog"
 	"time"
 	tgbotapi "github.com/go-telegram-bot-api/telegram-bot-api/v5"
 	"github.com/paramah/gw_telegram/internal/application/dto"
 	"github.com/paramah/gw_telegram/internal/application/usecase"
 )
 type TelegramHandler struct {
 	textUC  *usecase.HandleTextMessage
 	voiceUC *usecase.HandleVoiceMessage
 	logger  *slog.Logger
 }
 func NewTelegramHandler(
 	textUC *usecase.HandleTextMessage,
 	voiceUC *usecase.HandleVoiceMessage,
 	logger *slog.Logger,
 ) *TelegramHandler {
 	return &TelegramHandler{textUC: textUC, voiceUC: voiceUC, logger: logger}
 }
 func (h *TelegramHandler) Handle(ctx context.Context, update tgbotapi.Update) {
 	defer func() {
 		if r := recover(); r != nil {
 			h.logger.ErrorContext(ctx, "panic in update handler", "panic", r)
 		}
 	}()
 	if update.Message == nil {
 		return
 	}
 	msg := update.Message
 	switch {
 	case msg.Voice != nil:
 		in := dto.IncomingMessageDTO{
 			MessageID:   int64(msg.MessageID),
 			ChatID:      msg.Chat.ID,
 			UserID:      msg.From.ID,
 			Username:    msg.From.UserName,
 			FirstName:   msg.From.FirstName,
 			LastName:    msg.From.LastName,
 			VoiceFileID: msg.Voice.FileID,
 			IsVoice:     true,
 			Timestamp:   time.Unix(int64(msg.Date), 0),
 			Language:    msg.From.LanguageCode,
 		}
 		if err := h.voiceUC.Execute(ctx, in); err != nil {
 			h.logger.ErrorContext(ctx, "voice handler error", "error", err, "user_id", msg.From.ID)
 		}
 	case msg.Text != "":
 		in := dto.IncomingMessageDTO{
 			MessageID: int64(msg.MessageID),
 			ChatID:    msg.Chat.ID,
 			UserID:    msg.From.ID,
 			Username:  msg.From.UserName,
 			FirstName: msg.From.FirstName,
 			LastName:  msg.From.LastName,
 			Text:      msg.Text,
 			Timestamp: time.Unix(int64(msg.Date), 0),
 			Language:  msg.From.LanguageCode,
 		}
 		if err := h.textUC.Execute(ctx, in); err != nil {
 			h.logger.ErrorContext(ctx, "text handler error", "error", err, "user_id", msg.From.ID)
 		}
 	}
 }
--- a/test/testutil/fake_file_downloader.go
+++ b/test/testutil/fake_file_downloader.go
@@ -0,0 +1,25 @@
 package testutil
 import "context"
 type FakeFileDownloader struct {
 	Data     []byte
 	MimeType string
 	Error    error
 }
 func (f *FakeFileDownloader) Download(_ context.Context, _ string) ([]byte, string, error) {
 	return f.Data, f.MimeType, f.Error
 }
 type FakeAudioConverter struct {
 	Output []byte
 	Error  error
 }
 func (f *FakeAudioConverter) Convert(_ context.Context, _ []byte, _, _ string) ([]byte, error) {
 	if f.Output != nil {
 		return f.Output, f.Error
 	}
 	return []byte("converted-audio"), f.Error
 }
--- a/test/testutil/fake_intent_router.go
+++ b/test/testutil/fake_intent_router.go
@@ -0,0 +1,15 @@
 package testutil
 import (
 	"context"
 	"github.com/paramah/gw_telegram/internal/domain/entity"
 )
 type FakeIntentRouter struct {
 	RouteResult entity.Route
 	Error       error
 }
 func (f *FakeIntentRouter) Route(_ context.Context, _ entity.Message) (entity.Route, error) {
 	return f.RouteResult, f.Error
 }
--- a/test/testutil/fake_message_gateway.go
+++ b/test/testutil/fake_message_gateway.go
@@ -0,0 +1,22 @@
 package testutil
 import "context"
 type FakeMessageGateway struct {
 	LastSentText  string
 	LastChatID    int64
 	TypingChatIDs []int64
 	SendError     error
 	TypingError   error
 }
 func (f *FakeMessageGateway) SendText(_ context.Context, chatID int64, text string) error {
 	f.LastChatID = chatID
 	f.LastSentText = text
 	return f.SendError
 }
 func (f *FakeMessageGateway) SendTyping(_ context.Context, chatID int64) error {
 	f.TypingChatIDs = append(f.TypingChatIDs, chatID)
 	return f.TypingError
 }
--- a/test/testutil/fake_session_store.go
+++ b/test/testutil/fake_session_store.go
@@ -0,0 +1,43 @@
 package testutil
 import (
 	"context"
 	"github.com/paramah/gw_telegram/internal/domain/apperror"
 	"github.com/paramah/gw_telegram/internal/domain/entity"
 )
 type FakeSessionStore struct {
 	Sessions       map[int64]entity.Session
 	GetError       error
 	SetCalled      bool
 	LastSetSession entity.Session
 }
 func (f *FakeSessionStore) Get(_ context.Context, userID int64) (entity.Session, error) {
 	if f.GetError != nil {
 		return entity.Session{}, f.GetError
 	}
 	if f.Sessions != nil {
 		if s, ok := f.Sessions[userID]; ok {
 			return s, nil
 		}
 	}
 	return entity.Session{}, apperror.ErrSessionNotFound
 }
 func (f *FakeSessionStore) Set(_ context.Context, session entity.Session) error {
 	f.SetCalled = true
 	f.LastSetSession = session
 	if f.Sessions == nil {
 		f.Sessions = make(map[int64]entity.Session)
 	}
 	f.Sessions[session.UserID] = session
 	return nil
 }
 func (f *FakeSessionStore) Delete(_ context.Context, userID int64) error {
 	if f.Sessions != nil {
 		delete(f.Sessions, userID)
 	}
 	return nil
 }
--- a/test/testutil/fake_speech_transcriber.go
+++ b/test/testutil/fake_speech_transcriber.go
@@ -0,0 +1,14 @@
 package testutil
 import "context"
 type FakeSpeechTranscriber struct {
 	Transcript string
 	Error      error
 	CallCount  int
 }
 func (f *FakeSpeechTranscriber) Transcribe(_ context.Context, _ []byte, _ string) (string, error) {
 	f.CallCount++
 	return f.Transcript, f.Error
 }
--- a/test/testutil/fake_workflow_dispatcher.go
+++ b/test/testutil/fake_workflow_dispatcher.go
@@ -0,0 +1,19 @@
 package testutil
 import (
 	"context"
 	"github.com/paramah/gw_telegram/internal/domain/entity"
 )
 type FakeWorkflowDispatcher struct {
 	Response    entity.WorkflowResponse
 	Error       error
 	CallCount   int
 	LastRequest entity.WorkflowRequest
 }
 func (f *FakeWorkflowDispatcher) Dispatch(_ context.Context, req entity.WorkflowRequest) (entity.WorkflowResponse, error) {
 	f.CallCount++
 	f.LastRequest = req
 	return f.Response, f.Error
 }
--- a/test/testutil/fixtures.go
+++ b/test/testutil/fixtures.go
@@ -0,0 +1,29 @@
 package testutil
 import (
 	"time"
 	"github.com/paramah/gw_telegram/internal/domain/entity"
 )
 func NewTextMessage(chatID, userID int64, text string) entity.Message {
 	return entity.Message{
 		MessageID: 1,
 		ChatID:    chatID,
 		UserID:    userID,
 		Username:  "testuser",
 		Type:      entity.MessageTypeText,
 		Text:      text,
 		Timestamp: time.Now(),
 		Metadata:  make(map[string]any),
 	}
 }
 func NewSession(userID, chatID int64) entity.Session {
 	return entity.Session{
 		UserID:    userID,
 		ChatID:    chatID,
 		Data:      make(map[string]any),
 		UpdatedAt: time.Now(),
 		TTL:       24,
 	}
 }