Документация для разработчиков

Карта каталога internal-docs в репозитории — окружение, CI/CD, сущность Block, ADR

Зачем эта страница

Публичный сайт документации (/docs) описывает продукт и интеграции. Подробные материалы для разработчиков живут в корне репозитория в каталоге internal-docs/. После клонирования проекта открывайте их в IDE или на GitHub — отдельного зеркала на docs-сайте нет.

Ниже — ориентир: что где лежит и с чего начать.

Окружение и скрипты

Файл в репозитории	Содержание
`internal-docs/LOCAL_SETUP.md`	Копирование env (`example.env` → `.env.local`), обязательные переменные (Supabase, Better Auth, OAuth), `npm run check-env`, типичные ошибки
`internal-docs/SCRIPTS_REFERENCE.md`	Назначение `npm run check-env`, коды выхода, примеры вывода
`internal-docs/environment-checks.md`	Дополнительные проверки окружения
`internal-docs/fix-cloud-variables.md`	Настройка облачных переменных
`internal-docs/testing-setup.md`	Сведения по тестам
`.env.example` / `example.env`	Шаблоны переменных (в репозитории могут быть оба; сверяйтесь с актуальной веткой)

CI/CD

Файл	Содержание
`internal-docs/CICD_SETUP.md`	Настройка пайплайнов
`internal-docs/CICD_CHECKLIST.md`	Чек-лист перед релизом
`internal-docs/ci-simplification.md`	Упрощения CI
`internal-docs/github-secrets-setup.md`	Секреты в GitHub

Сущность Block (углублённо)

Пользовательский обзор: Блоковая модель данных.

В internal-docs/entities/block/ — материалы для работы с кодом блоков:

readme.md — входная точка, принципы, ссылки на типы в entities/block/types/blockTypes.ts
architecture/overview.md — архитектура
technical/architecture-diagrams.md — диаграммы
api/types.md — типы API
hooks/use-blocks.md — хуки
components/overview.md — обзор компонентов
patterns/creating-blocks.md — паттерны создания
layout-modes/ — list-mode.md, grid-mode.md, flow-mode.md
block-types/ — правила по типам: text.md, todo.md, container.md, media.md, link.md, table.md, calendar.md, timeslot.md, unit_ref.md и др.
examples/simple-list.md — пример

Имеет смысл открывать соответствующий block-types/*.md перед изменением конкретного типа блока.

Архитектурные решения (ADR)

Индекс: internal-docs/adr/README.md.

Там перечислены записи в подпапках architecture/, errors/, other/ (шаблон, правила именования файлов). Для спорных изменений в кодовой базе сначала проверьте, нет ли уже принятого ADR.

Прочее

Файл	Название темы
`internal-docs/ai-migration-guide.md`	Миграции вокруг AI
`internal-docs/react-query-migration.md`	React Query
`internal-docs/timeline-simulator-roadmap.md`	Roadmap симулятора
`internal-docs/timelix-entity-relationships.excalidraw`	Диаграмма связей сущностей (Excalidraw)
`internal-docs/archive/`	Архивные заметки (например разовые ф ix)

Как предлагать правки

Добавляйте и правите файлы прямо в internal-docs/ в том же PR, что и код, если документация относится к изменению. Эту страницу на сайте /docs/contributing стоит обновлять, когда появляется новый крупный подкаталог или кардинально меняется точка входа (например перенос ADR).