docs: add full project documentation

- Architecture: overview, 7 ADR, tech stack
- Principles: code-style, git-workflow, security
- API contracts: auth, profile, tests, admin endpoints
- Database schema: tables, relationships, indexes
- LLM strategy: prompts, fallback, validation, Qwen 2.5 14B
- Onboarding: setup, Docker, .env template
- Progress: roadmap, changelog
- Agents: context, backend instructions

Made-with: Cursor

architecture/decisions/005-llm-abstraction.md

@@ -0,0 +1,45 @@
+# ADR-005: Абстракция LLM через LlmService
+
+## Статус
+
+Принято
+
+## Контекст
+
+Приложение использует LLM для генерации вопросов, проверки ответов и рекомендаций. Нужна возможность менять провайдера без изменения бизнес-логики.
+
+## Решение
+
+Весь доступ к LLM только через `LlmService`. Конфигурация провайдера — через переменные окружения:
+
+```
+LLM_BASE_URL=http://localhost:11434/v1    # Ollama (runtime для backend)
+LLM_MODEL=qwen2.5:14b
+LLM_API_KEY=                               # пустой для локального
+LLM_TIMEOUT_MS=15000
+LLM_MAX_RETRIES=1
+```
+
+### Стратегия провайдеров
+
+1. **Dev/test** — локальный LLM (Ollama, LM Studio, vLLM) с OpenAI-совместимым API
+2. **Production** — облачный API (OpenAI, Anthropic и др.)
+3. Переключение — замена переменных в `.env`, код приложения не меняется
+
+### Интерфейс LlmService
+
+- `generateQuestions(stack, level, count, type)` → structured JSON
+- `verifyAnswer(question, userAnswer)` → boolean + explanation
+- `getHint(question)` → string
+- `getRecommendations(weakTopics)` → string[]
+
+### Fallback
+
+Если LLM недоступен или таймаут — берём вопросы из `question_bank` (предварительно наполненного через тот же LLM и провалидированного вручную).
+
+## Последствия
+
+- Бизнес-код не зависит от конкретного провайдера
+- Замена LLM — изменение одного `.env` файла
+- Нужен минимальный банк вопросов для fallback до запуска
+- Все ответы LLM валидируются по JSON-схеме перед использованием