gooseek/backend/README.md

# GooSeek Backend (Go)

Perplexity-style AI Search Backend на Go.

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

```
backend/
├── cmd/                    # Точки входа
│   ├── api-gateway/        # API Gateway (HTTP proxy + routing)
│   ├── chat-svc/           # Chat orchestration service
│   ├── search-svc/         # SearXNG wrapper
│   ├── llm-svc/            # LLM providers abstraction
│   ├── scraper-svc/        # Web scraping (Crawl4AI-like)
│   ├── agent-svc/          # AI Agent (search orchestrator)
│   ├── discover-svc/       # Discover (article summaries)
│   ├── collection-svc/     # Collections (saved research)
│   ├── file-svc/           # File upload & analysis
│   └── thread-svc/         # Threads, Spaces, Memory, Pages
├── internal/               # Внутренние пакеты
│   ├── agent/              # Search orchestrator logic
│   │   ├── classifier.go   # Query classifier
│   │   ├── researcher.go   # Research agent
│   │   ├── writer.go       # Response writer
│   │   └── orchestrator.go # Main orchestration
│   ├── llm/                # LLM abstractions
│   │   ├── client.go       # Generic LLM client
│   │   ├── openai.go       # OpenAI provider
│   │   ├── anthropic.go    # Anthropic provider
│   │   └── gemini.go       # Google Gemini
│   ├── search/             # Search integrations
│   │   ├── searxng.go      # SearXNG client
│   │   ├── media.go        # Image/video search
│   │   └── reranker.go     # BM25 reranking
│   ├── scraper/            # Web scraping
│   │   ├── crawler.go      # Page crawler
│   │   ├── parser.go       # HTML parser
│   │   └── cache.go        # Scrape cache
│   ├── widgets/            # Widget generation
│   │   ├── weather.go      # Weather widget
│   │   ├── calculator.go   # Calculator widget
│   │   └── registry.go     # Widget registry
│   ├── session/            # Session management
│   │   ├── manager.go      # Session manager
│   │   └── events.go       # Event emitter
│   ├── prompts/            # LLM prompts
│   │   ├── classifier.go   # Classification prompts
│   │   ├── researcher.go   # Research prompts
│   │   └── writer.go       # Writer prompts
│   └── types/              # Shared types
│       ├── blocks.go       # Response blocks
│       ├── chunks.go       # Search chunks
│       └── widgets.go      # Widget types
├── pkg/                    # Public packages
│   ├── ndjson/             # NDJSON streaming
│   ├── middleware/         # HTTP middleware
│   └── config/             # Configuration
├── api/                    # API definitions
│   └── proto/              # gRPC definitions (optional)
├── deploy/                 # Deployment configs
│   ├── docker/             # Dockerfiles
│   └── k8s/                # Kubernetes manifests
├── go.mod
├── go.sum
└── Makefile
```

## Сервисы

### 1. API Gateway (port 3015)
HTTP прокси для роутинга запросов к микросервисам.

### 2. Chat Service (port 3005)
Оркестрация чат-запросов, интеграция с agent-svc.

### 3. Agent Service (port 3018)
Главная логика Perplexity-style поиска:
- Query classification
- Multi-step research
- Response generation with citations

### 4. Search Service (port 3001)
SearXNG wrapper для веб-поиска.

### 5. LLM Service (port 3020)
Абстракция над LLM провайдерами.

### 6. Scraper Service (port 3021)
Web scraping для получения контента страниц.

### 7. Discover Service (port 3002)
Perplexity-style Discover функционал:
- Article summaries (дайджесты статей)
- Digest generation и кэширование
- Pre-generated digests storage
- Redis + PostgreSQL персистентность

### 8. Collection Service (port 3025)
Perplexity Collections:
- Сохранение исследований в проекты
- Контекст коллекции для новых поисков
- Шаринг коллекций
- CRUD для items (searches, notes, urls, files)

### 9. File Service (port 3026)
Perplexity File Analysis:
- Загрузка PDF, images, text файлов
- Автоматический анализ через LLM
- Извлечение текста из PDF
- Vision analysis для изображений
- Интеграция с Collections

### 10. Thread Service (port 3027)
Полный функционал сессий и персонализации:

**Threads (Chat History)**:
- Сохранение истории чатов в PostgreSQL
- Автогенерация заголовков
- Пагинация сообщений
- Sharing по публичной ссылке

**Spaces (Workspaces)**:
- Custom AI instructions per space
- Default focus mode и model
- Организация threads по проектам
- Цветовые теги и иконки

**Pages (Article Generator)**:
- Генерация статей из threads
- Форматированные секции с цитатами
- Экспорт в Markdown/HTML
- Публичный sharing

**Memory (Personalization)**:
- Сохранение предпочтений пользователя
- Фактов о пользователе
- Custom instructions
- Контекст для всех сессий

## Запуск

```bash
# Development
make dev

# Build all
make build

# Docker
make docker-build
make docker-up

# Tests
make test
```

## API

### POST /api/chat (NDJSON stream)
```json
{
  "message": {
    "messageId": "uuid",
    "chatId": "uuid",
    "content": "What is quantum computing?"
  },
  "optimizationMode": "speed|balanced|quality",
  "chatModel": {
    "providerId": "openai",
    "key": "gpt-4o"
  },
  "history": [["human", "..."], ["ai", "..."]],
  "locale": "ru"
}
```

### Response (NDJSON)
```
{"type":"block","block":{"id":"...","type":"research","data":{...}}}
{"type":"block","block":{"id":"...","type":"source","data":[...]}}
{"type":"block","block":{"id":"...","type":"widget","data":{...}}}
{"type":"textChunk","blockId":"...","chunk":"Квантовые..."}
{"type":"messageEnd"}
```

## Режимы оптимизации

| Mode     | Time    | LLM Calls | Scraping |
|----------|---------|-----------|----------|
| Speed    | 8-15s   | 1         | No       |
| Balanced | 20-40s  | 2-3       | Top 5    |
| Quality  | 60-120s | 5-10      | Top 15   |

## Perplexity-style Features

### Focus Modes
- **All** — полный веб-поиск
- **Academic** — Google Scholar, ArXiv, PubMed
- **YouTube** — видео контент
- **Reddit** — обсуждения сообщества
- **Code** — GitHub, StackOverflow
- **News** — актуальные новости
- **Math** — Wolfram Alpha, вычисления
- **Finance** — финансовые данные

### Deep Research
Multi-agent система глубокого исследования:
- Автоматическое разбиение на подзапросы
- 30+ поисков, 100+ источников
- Итеративный поиск с follow-up
- Синтез инсайтов
- Генерация отчёта с цитатами

### Collections
- Сохранение исследований в проекты
- Контекст коллекции для новых поисков
- Типы items: search, note, url, file
- Шаринг коллекций

### File Analysis
- PDF extraction
- Image analysis (vision models)
- Text file processing
- Интеграция с поиском

### Clarifying Questions (Pro Search)
- Автоматическое определение неоднозначных запросов
- 2-3 уточняющих вопроса перед поиском
- Работает в Quality mode

### Related Questions
- Генерация 3-4 связанных вопросов после ответа
- На основе контекста запроса и ответа
- Поддержка локализации (ru/en)

### Spaces & Pages
- **Spaces**: workspaces с custom instructions
- **Pages**: генерация статей из исследований
- Публичный sharing по ссылке
- Счётчик просмотров

### Memory & Personalization
- Сохранение предпочтений пользователя
- Типы: preference, fact, instruction, interest
- Автоматический контекст в каждом запросе
- Importance scoring

## Технологии

- **HTTP**: Fiber v2
- **Streaming**: NDJSON over HTTP
- **LLM**: OpenAI, Anthropic, Gemini
- **Search**: SearXNG
- **Scraping**: Crawl4AI / custom crawler
- **Caching**: Redis
- **Database**: PostgreSQL
- **Auth**: JWT validation