# gitaspen docs

Раскладка кода по слоям, разворачивание и эксплуатация, правила работы и дизайн интерфейса — то, что одинаково для всех проектов.

## Общее

- [Маршруты чтения](http://docs.gitaspen.ru/raw/ROUTES): Что читать под конкретную задачу и в каком порядке. Каждый маршрут собран так, чтобы после него задачу можно было выполнить целиком, не догадываясь о пропущенном.

## Разработка / Архитектура

Раскладка кода по слоям: приложение целиком, фронт, бэк, шлюз, переиспользование и доступ.

- [BMAP — Base Multi Application Platform](http://docs.gitaspen.ru/raw/development/architecture/BMAP): Архитектура приложения целиком: репозиторий, в котором живут фронты (BMFP) и бэки (BMBP), и способ их сборки в один продукт. BMAP описывает только корни репозитория и границы между ними; внутреннее устройство — в BMFP, BMBP, BMGP.
- [BMBP — Base Multi Backend Platform](http://docs.gitaspen.ru/raw/development/architecture/BMBP): Архитектура бэкенда: сервиса, API, монолита или бэкенда для приложения, любого размера и для любого транспорта (синхронные запросы, события, реалтайм).
- [BMFP — Base Multi Front Platform](http://docs.gitaspen.ru/raw/development/architecture/BMFP): Архитектура фронтенда: сайта, веб-приложения, UI десктоп-приложения, мини-аппа. Одна и та же раскладка слоёв работает для любого UI независимо от того, есть ли за ним бэкенд.
- [BMGP — Base Multi Gateway Platform](http://docs.gitaspen.ru/raw/development/architecture/BMGP): Шлюз — реверс-прокси под конкретный фронт. Собирает в одно API ручки из нескольких бэков (BMBP), нужных этому фронту. Фронт ходит только в свой шлюз и не знает, сколько за ним бэков и какие они. Состав шлюза определяется со стороны фронта («какие ручки мне нужны»), не со стороны бэка («как я сгруппирован»). Один фронт — один шлюз.
- [REUSE — конфлюэнтность и переиспользование](http://docs.gitaspen.ru/raw/development/architecture/REUSE): Один закон, работающий на всех уровнях гранулярности: то же, что делает хорошим коммит, делает хорошим модуль, компонент, движок и продукт. BM (BMFP / BMBP / BMAP) описывает один продукт изнутри. Этот документ — как единицы переиспользуются между продуктами и как это удерживается в git.
- [Аутентификация и авторизация](http://docs.gitaspen.ru/raw/development/architecture/AUTH): Как система устанавливает, кто обращается, и как решает, что этому обратившемуся разрешено. Документ задаёт раскладку: какая проверка живёт в каком слое, какие бывают удостоверения и сколько живёт каждое, как устроен единый вход между несколькими сервисами, как выражается правило доступа, как выглядит отказ и как убедиться, что код этой раскладке отвечает.
- [Принципы разработки](http://docs.gitaspen.ru/raw/development/architecture/PRINCIPLES): Как мы строим всё. Коротко — чтобы пересказать своими словами; полно — чтобы закрывать споры. Это верхний слой; «как именно» — в спеках рядом: BMAP (приложение целиком), BMFP (фронт), BMBP (бэкенд), BMGP (шлюз), REUSE (переиспользование).

## Разработка / Дизайн

Правила интерфейса: раскладка на разных экранах, визуальная проработка, карты источников.

- [DESIGN RULES](http://docs.gitaspen.ru/raw/development/design/DESIGN_RULES): Версия: 2026-06-22.
- [RESPONSIVE — правило адаптива](http://docs.gitaspen.ru/raw/development/design/RESPONSIVE): Версия: 2026-06-29.
- [Атлас областей дизайна интерфейсов](http://docs.gitaspen.ru/raw/development/design/design-atlas): Жанр: карта источников. По этому файлу нельзя выполнить задачу, не обращаясь наружу, — он показывает, какие дисциплины существуют и куда идти за глубиной. Практические правила, по которым делают и ревьюят интерфейс, — в DESIGN_RULES.md.
- [Визуальное ремесло: как делать «дорого» и современно](http://docs.gitaspen.ru/raw/development/design/visual-craft-premium): Источник: разбор трёх Instagram-профилей через визуальный анализ ~30 работ — @orbixstudiollc (сайты/лендинги), @orbixdashboard (дашборды), @webdesignssphere (веб-дизайн).
- [Книжная карта по дизайну интерфейсов](http://docs.gitaspen.ru/raw/development/design/design-books-core-reading-map): Жанр: карта источников. Файл не заменяет чтение и не пересказывает книги целиком — по нему нельзя выполнить задачу, не обращаясь наружу.

## Разработка / Дизайн / codex design rules skill

- [Design Rules](http://docs.gitaspen.ru/raw/development/design/codex-design-rules-skill/SKILL): Derived version of the library's design/DESIGN_RULES.md, packaged in English for installation as a skill; that file is the source of truth, and changes go there first.

## Разработка / Правила работы

Как писать код и документы: стиль, тесты, история изменений, язык документации.

- [Как писать документ библиотеки](http://docs.gitaspen.ru/raw/development/process/writing-a-library-document): Требования к документам этой библиотеки. Общие правила языка и тона — в правилах письма; здесь — что именно должно быть в документе, чтобы им можно было пользоваться.
- [Правила письма: документация, статьи, тексты](http://docs.gitaspen.ru/raw/development/process/writing-rules): Перечитывать перед написанием любого текста для чтения людьми: документация, README, спека, описание формата/продукта, статья, пост, коммит-описание уровня документа. Цель — текст уровня технической документации и научной статьи, а не маркетинга.
- [Работа в кодовой базе](http://docs.gitaspen.ru/raw/development/process/rules): Как вносится отдельное изменение в код: с чем сверяются до, как правят, что проверяют перед сдачей и что делают при расхождении с архитектурой. Правила одинаковы для человека и для ИИ-помощника: у кода два равных пользователя, оба действуют одной логикой и видят одни и те же документы (PRINCIPLES).
- [Работа с git и репозиториями](http://docs.gitaspen.ru/raw/development/process/git-and-repositories): Повседневные правила: что попадает в историю, как выглядит коммит, как ведутся ветки и версии, что делать при ошибке. Границы репозиториев и выделение переиспользуемых единиц — в REUSE; здесь то, что происходит внутри репозитория каждый день.
- [Стиль кода бэкенда](http://docs.gitaspen.ru/raw/development/process/backend-code-style): Как выглядит код внутри слоя: имена, типизация, исключения, асинхронность, записи в журнал, комментарии, размер единиц. Раскладка по слоям, иерархия маршрутов, конверт ответа, три модели данных, идемпотентность, транзакции и таймауты — в BMBP. Формат записи журнала, уровни и срок хранения — в наблюдении за системой. Хранение самих секретов — в работе с секретами. Здесь только то, что решается при написании модуля.
- [Стиль кода фронтенда](http://docs.gitaspen.ru/raw/development/process/frontend-code-style): Как выглядит код внутри одного файла компонента: структура разметки, вложенность стилей, имена, комментарии, приёмы взаимодействия. Раскладка по слоям, границы импортов и правило «стиль лежит рядом с компонентом» — в BMFP. Роли цвета, типографика, обязательные состояния экрана — в правилах дизайна, единицы и точки перестроения — в адаптивности. Здесь только то, что решается внутри файла.
- [Тестирование](http://docs.gitaspen.ru/raw/development/process/testing): Что покрывать тестами, какими именно и где они лежат. Документ общий для фронта и бэка: слои разные, принцип один — тест проверяет наблюдаемое поведение через границу, а не внутреннее устройство.

## Разработка / Эксплуатация

От чистой машины до выката: сеть, контейнеры, база, секреты, копии, наблюдение.

- [Docker на сервере: установка, настройка, обслуживание](http://docs.gitaspen.ru/raw/development/operations/docker-install): Инструкция доводит чистый сервер до состояния «Docker и Compose работают, приложения публикуются безопасно, диск не забивается логами». Отдельным разделом — полная переустановка, когда прежняя установка сломана.
- [HTTPS для домена: nginx + Let's Encrypt](http://docs.gitaspen.ru/raw/development/operations/tls-certificates): Инструкция доводит сервер от «есть чистая машина и домен» до «сайт открывается по HTTPS, сертификат продлевается сам». Каждый шаг заканчивается проверкой с однозначным ожидаемым результатом: если результат другой — переходите к разделу «Типичные отказы», не выполняя следующий шаг.
- [База данных: постановка, схемы, миграции](http://docs.gitaspen.ru/raw/development/operations/database): Как довести хранилище от «базы нет» до состояния «сервисы работают со своими схемами, изменения схемы выкатываются и откатываются». Документ описывает PostgreSQL; в нём два способа постановки — своя база в контейнере рядом с сервисом и внешняя управляемая база у провайдера.
- [Базовая настройка сервера: от выдачи машины до готовности к Docker](http://docs.gitaspen.ru/raw/development/operations/server-setup): Инструкция доводит только что выданную машину до состояния, с которого начинается установка Docker: система обновлена, работа идёт под отдельным пользователем, вход — только по ключу, межсетевой экран включён, время синхронизировано, журналы ограничены по размеру. Каждый шаг заканчивается проверкой с однозначным ожидаемым результатом: если результат другой — переходите к разделу «Типичные отказы», не выполняя следующий шаг.
- [Журналы: формат, сбор, хранение](http://docs.gitaspen.ru/raw/development/operations/logs): Документ доводит установку от «сервисы что-то пишут в вывод контейнера» до «записи всех сервисов лежат в одном месте, ищутся по идентификатору запроса, хранятся ограниченный срок и не содержат секретов».
- [Запуск приложения на сервере: файл compose, сети, проверки](http://docs.gitaspen.ru/raw/development/operations/running-an-application): Как довести сервер от состояния «Docker установлен, код и значения на месте» до состояния «приложение работает, шлюз отвечает на 127.0.0.1:8000, наружу не смотрит ни одна часть». Это то исходное состояние, которое требуют HTTPS для домена и релиз и выкат: оба начинают с работающего шлюза на loopback.
- [Наблюдение: метрики, показ, оповещения](http://docs.gitaspen.ru/raw/development/operations/observability): Документ доводит установку от «сервис выкачен и закрыт шлюзом» до «числа снимаются, графики открываются, оповещение приходит на проверенный отказ». Каждый шаг заканчивается проверкой с однозначным ожидаемым результатом: если результат другой — переходите к разделу «Типичные отказы», не выполняя следующий шаг.
- [Обмен сообщениями между сервисами: Kafka](http://docs.gitaspen.ru/raw/development/operations/message-queues): Как довести обмен от «сервисы дёргают друг друга запросами» до состояния «работает брокер, темы созданы с известными настройками, события публикуются без потерь, неразобранное складывается отдельно и разбирается». Документ описывает контракт сообщений и постановку Kafka в контейнерах рядом с приложением.
- [Резервное копирование и восстановление](http://docs.gitaspen.ru/raw/development/operations/backup-and-restore): Что копировать, куда, как проверять и как восстанавливаться. Документ исходит из того, что резервная копия существует не сама по себе, а ради восстановления: непроверенная копия равнозначна её отсутствию.
- [Релиз и выкат без простоя](http://docs.gitaspen.ru/raw/development/operations/release-and-deploy): Как собрать воспроизводимый релиз и выкатить его так, чтобы пользователи не увидели перерыва, а неудачный выкат откатывался за секунды.
- [Секреты: хранение, доставка, ротация](http://docs.gitaspen.ru/raw/development/operations/secrets): Документ доводит систему до состояния «ни одно секретное значение не лежит в репозитории и в образе; рядом с каждой частью системы лежит её файл значений; значение заменяется без простоя». Исходное состояние: репозиторий с кодом, части системы описаны файлами compose, сервер с Docker.
- [Сетевой контур: от домена до микросервиса](http://docs.gitaspen.ru/raw/development/operations/network-topology): Как трафик доходит от браузера до кода микросервиса и почему на пути стоит несколько nginx. Схема описана для распределённой установки, где микросервисы живут на разных серверах и соединены частной сетью.
- [Частная сеть между серверами](http://docs.gitaspen.ru/raw/development/operations/private-network): Инструкция соединяет несколько серверов частной сетью на WireGuard: у каждой машины появляется адрес, по которому её видят остальные машины контура и не видит интернет. После выполнения сервисы обращаются друг к другу по этим адресам, а наружу по-прежнему смотрят только порты 80 и 443 на сервере шлюза.