# Контекст проекта для AI-агентов

Этот документ — краткое описание проекта для использования AI-ассистентами при генерации кода.

## Проект

**samreshu** — веб-приложение для тестирования знаний по веб-технологиям. Пользователь выбирает стек и уровень, получает тест из вопросов (сгенерированных LLM или из банка), отвечает и видит результат с разбором.

## Tech stack

- **Backend**: Fastify + TypeScript, Drizzle ORM, PostgreSQL, Redis
- **Frontend**: React + TypeScript + Vite
- **LLM**: Локальный (Ollama/LM Studio, OpenAI-совместимый API), в prod — облачный
- **Логирование**: Pino
- **Тесты**: Vitest
- **Deploy**: VPS + Docker Compose

## Архитектурные принципы (обязательны)

1. Подписка пользователя читается из БД через subscription middleware — не хардкодить права в контроллерах
2. Вопросы копируются в `test_questions` при старте теста (снепшот) — не читать `question_bank` во время теста
3. Все LLM-вызовы только через `LlmService` — код не знает какая модель работает
4. Все внешние данные (webhooks, LLM) валидируются по JSON-схеме
5. Проверки прав и лимитов только на backend — frontend отображает состояние
6. Все даты хранятся в UTC — конвертация только на фронте
7. Конфигурация через env переменные — без хардкодов

## Code style

- Язык кода: английский
- Язык коммитов: английский (conventional commits)
- TypeScript strict, `any` запрещён
- `console.log` запрещён — использовать Pino logger
- Prettier + ESLint strict + security plugin

## Структура репозиториев

```text
samreshu-backend       Fastify + TS + Drizzle
samreshu-frontend      React + TS + Vite
samreshu-docs          Документация
```

Общие типы хранятся в каждом репо отдельно.

## Где найти детали

- Схема БД: `database/schema.md`
- API контракты: `api/contracts.md`
- LLM стратегия: `llm/strategy.md`
- Roadmap: `progress/roadmap.md`
- Code style: `principles/code-style.md`

## Инструкции для агентов в code-репо

В каждом code-репо будет `.cursor/rules/` со специфичными инструкциями:

- Backend: структура папок, как писать сервисы/плагины Fastify, Drizzle-паттерны
- Frontend: структура компонентов, state management, роутинг