# ADR-0001. Модульный монолит на Laravel

- Статус: принято
- Дата: 2026-09-30

## Контекст

Небольшая команда строит продукт с горячим путём (обработка чеков на кассе) и широкой периферией
(кабинеты, акции, коммуникации, отчёты, биллинг). Исследование показывает, что успешные системы
начинали с монолита, а Shopify смог заменить целые подсистемы благодаря жёстким границам модулей.
Обработку чеков, возможно, придётся вынести в отдельный сервис (например, на Go), если после
оптимизации не будет выдерживаться SLO.

## Решение

- Один деплой Laravel 13 на PHP 8.5, код разбит на модули `app-modules/<module>` пакетом
  `internachi/modular`. Каждый модуль — Composer-пакет с пространством имён `Modules\<Module>`,
  собственными маршрутами, миграциями, фабриками и тестами.
- Публичный API модуля — только пространства `Modules\<Module>\Contracts` (интерфейсы, DTO,
  value objects, enum'ы) и `Modules\<Module>\Events` (доменные события). Всё остальное — внутреннее.
- Модули зависят друг от друга только через публичный API. Исключение — модуль `kernel`
  (общее ядро): его может использовать любой модуль. Правила проверяются Deptrac и архитектурными
  тестами Pest в CI.
- Связи Eloquent между моделями разных модулей запрещены: другие модули ссылаются на сущность
  по идентификатору и получают данные через контракт.
- Базовая зависимость модулей: `kernel` ← `tenancy` ← предметные модули (`programs`, `ledger`,
  `members`, `rules`, `processing` …) ← интерфейсы (кабинеты).

## Последствия

- Горячий путь можно вынести в отдельный сервис, заменив реализацию контрактов, без переписывания
  остальных модулей.
- Больше шаблонного кода на границах (DTO, интерфейсы) — осознанная цена.
- Новый модуль создаётся командой `php artisan make:module <name>` и обязательно добавляется
  в `deptrac.yaml`.