Files

Anton 99cd8ae727 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

2026-03-04 12:07:17 +03:00

3.1 KiB

Raw Permalink Blame History

Контекст проекта для 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

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

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

Code style

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

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

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, роутинг

3.1 KiB Raw Permalink Blame History Unescape Escape