Почему такой стек

Проект собран неспроста, каждый выбор был обоснован. Если вы сделали иначе и можете объяснить, почему — это ровно тот разговор, который нам интересен: пишите в LOGBOOK.md.

Backend

• PHP 8.5 + Slim 4 — это тонкий микрофреймворк, а не тяжеловесные Laravel или Symfony: видно, как устроено приложение; фреймворк ничего не прячет.
• Cycle ORM — схема задаётся массивом, домен остаётся чистым: без аннотаций в сущностях и без компиляции на каждый запрос.
• SQLite — ноль настройки, база — это один файл. Для небольших объёмов достаточно; PostgreSQL был бы избыточен для нужд заказчика.
• id — это UUIDv7, а момент создания берём из самого id — сортируемый ключ и время «бесплатно», без автоинкремента и колонки created_at.

Frontend

• TypeScript + Vite, без UI-фреймворка. Видно платформу, а не абстракции React или Vue. Захотите фреймворк — обоснуйте, зачем он здесь.

Соглашения и проверки

• OpenAPIФормат описания HTTP-API. Схема в spec/api/openapi.yaml — источник истины для запросов и ответов. (spec/api/openapi.yaml) — схема первична: и фронтенд, и проверки опираются на неё.
• HurlТекстовый формат HTTP-проверок: запрос плюс ассерты на статус, заголовки и тело. Дружит с git и CI. обеспечивает приёмочные проверкиПроверки готовности: по контракту (Hurl) и несколько UI-сценариев (Playwright). Намеренно нестрогие. через файлы с одноимённым расширением, которые запускаются в CIContinuous Integration — автопрогон проверок на каждый push. Здесь гоняет тот же just verify, что и у вас локально.. Удобнее, чем держать коллекцию в Postman.
• PlaywrightБраузерные end-to-end тесты: открывают страницу и проходят сценарий как живой пользователь. — несколько UI-сценариев поверх контракта.

Дисциплина

• Строгий статанализПроверка кода без запуска: типы, стиль, «запахи» (PHPStan, PHPMD, Rector, ESLint). (PHPStan на уровне max+strict, PHPMD, Rector; ESLint с type-aware правилами, Prettier) — мы держим планку качества кода, критичную для разработки современных проектов.
• Лимиты памяти (96M / 256M) — приближаем условия разработки к скромному серверу заказчика, чтобы исключить неожиданности при деплое.
• devbox — окружение разворачивается одной командой и одинаково у всех, без «поставьте десять инструментов руками».

Этот сайт

Сам гайд собран на Typst + Tola. Инструкция живёт рядом с кодом и собирается в статический сайт. Typst хорош тем, что читается как Markdown, но под капотом полноценный язык программирования, который легко конвертируется в PDF, если вам так удобнее.

Цифры выше — не переписаны вручную: лимиты памяти страница читает прямо из .env.example через data-loading Typst, поэтому инструкция не может разойтись с конфигом.

А ещё Typst даёт хорошую ссылочность. Когда в тексте встречается термин, к нему всплывает подсказка — все они собраны в глоссарий. На термины мы ссылаемся через код, так что при их переименовании или удалении LSPLanguage Server Protocol — по нему редактор даёт автодополнение, переходы и поиск использований. Термины глоссария адресуются по коду, поэтому LSP находит все места, где термин употреблён. и компилятор сразу покажут, где термин ещё используется.