99cd8ae727
- 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
60 lines
3.1 KiB
Markdown
60 lines
3.1 KiB
Markdown
# Контекст проекта для 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, роутинг
|