# Обзор архитектуры

## Тип проекта

Структурированный монолит PHP с модульным дополнительным слоем.

- Никакого DDD, никакой гексагональности, никакой чистой архитектуры — намеренно.
- Split by context with minimal abstractions: `Controller → Service → Repository`.
- Два артефакта сборки из одной кодовой базы: **MAIN** (полная панель) и **LB** (подмножество load balancer).

---

## Дерево исходных текстов

|Путь|Роль|
| ---- | ---- |
| `src/Core/` |Примитивы инфраструктуры: Контейнер DI, события, HTTP, настройка, аутентификация, ведение журнала|
| `src/Domain/` |Бизнес-контексты: Поток, VOD, линия, пользователь, сервер, безопасность и т.д.|
| `src/Modules/` |Дополнительный слой расширения — загружается с помощью `ModuleLoader`|
| `src/Public/` |Передний контроллер, маршрутизатор, контроллеры, представления, ресурсы|
| `src/Cli/` |Консольные команды и точки входа в cron|
| `src/Ministra/` | Stalker Portal — in core; served at `/home/xc_vm/Ministra` |

---

## Модель времени выполнения

Зависимости перетекают друг в друга — модули могут использовать ядро и домен, но никогда наоборот.

```
Public/index.php
    └── XC_Bootstrap::boot(BootContext::ADMIN)
            └── ServiceContainer (DI)
                    ├── EventDispatcher (PSR-14)
                    ├── ModuleLoader → loadAll() → bootAll()
                    └── Router → dispatch()
```

Классы домена получают базу данных посредством внедрения `setDb()` (вызывается из
`bootstrap.php::wireDomainDatabase()`). Нет `global $db` в пути веб-запроса.

---

## Модульная система

Модули представляют собой изолированные каталоги под `src/Modules/` с манифестом `module.json`
и класс, расширяющий `BaseModule`. Полную информацию смотрите в разделе [Модульная система](modules.md).

```
src/Modules/my-module/
├── module.json          # metadata
├── MyModuleModule.php   # extends BaseModule, namespace XcVm\Module\MyModule
└── ...
```

---

## Контексты начальной загрузки

Четыре контекста определяют, какие подсистемы инициализируются. Смотрите [Контексты начальной загрузки](bootstrap-contexts.md).

|Контекст|Используется для|
| ------- | -------- |
| `BootContext::MINIMAL` |Скрипты, которым нужны только пути / конфигурация|
| `BootContext::CLI` |Задания Cron и команды CLI|
| `BootContext::STREAM` |Конечные точки потоковой передачи|
| `BootContext::ADMIN` |Панель администратора/реселлера|

---

## Варианты сборки (ОСНОВНАЯ и LB)

| |главный|фунт|
| --- | ---- | -- |
|Панель администратора|✅|❌|
|Потоковый|✅|✅|
|Модульная система|✅|подмножество|

Управляется перечислением `ServerEnvironment` и полем `module.json` `environment` (`main` / `lb` / `any`).

---

## Ключевые моменты расширения

|Механизм|Как использовать|
| --------- | ---------- |
|События PSR-14|атрибут `EventDispatcher::listen()` или `#[ListensTo]`|
|Оформление сервиса| `$container->decorate('id', callable, priority)` |
|Потоковое промежуточное программное обеспечение|Реализовать `StreamMiddlewareProviderInterface`|
|Записи Cron|Переопределить `getCronEntries()` в классе модуля|
|Миграции баз данных|Реализовать `MigratableInterface::getMigrations()`|

---

## Правила для участников

1. Модули не должны изменять основные файлы.
2. Никаких `eval`, исправлений ошибок или замены файлов во время выполнения.
3. Любой модуль можно отключить с помощью `config/modules.php`, не прикасаясь к ядру.
4. Защищенные сервисы (`db`, `settings`, `config`, `auth`) не могут быть оформлены.
5. Синхронизируйте документы EN и RU в одном и том же коммите.

## Связанные файлы

|Файл|Роль|
| --- | --- |
| `src/Core/` |Примитивы фреймворка (DI, события, HTTP, config, auth, ведение журнала)|
| `src/Domain/` |Бизнес-контексты (Поток, VOD, строка, Пользователь, Сервер, безопасность)|
| `src/Infrastructure/` |Внешние адаптеры (DatabaseFactory, CacheReader, Redis)|
| `src/Streaming/` |Подсистема потоковой передачи|
| `src/Modules/` |Дополнительные модули (загружаются с помощью ModuleLoader)|
| `src/Public/` |Передний контроллер, контроллеры, виды|
| `src/Cli/` |Консольные команды и задания cron|