Архитектура

Фреймворк Medusa использует компактную структуру: основной код находится в каталоге www/, а дополнительные настройки и данные вынесены в корень проекта. Ниже перечислены ключевые файлы и директории.

Каталог www/

Объект	Назначение
`.htaccess`	Правила Apache: кодировка по умолчанию UTF-8; отключён листинг каталогов; разрешены симлинки; задан индексный файл `medusa/index.php`; отключён вывод PHP-ошибок; включено логирование PHP-ошибок в `logs/php_errors.log`; все запросы, которые не совпали с реальным файлом, директорией или симлинком, перенаправляются в `medusa/index.php`.
`.env`	Смонтированный из корня файл с переменными окружения. В Docker-окружении источником служит корневой `.env`, а при его отсутствии — `.env.example`. Файл содержит параметры: `APP_URL`, `PDO_USER`, `PDO_PASSWORD`, `FROM_MAIL` и т.д.
`init.php`	Пользовательский bootstrap-файл.
`error.php`	HTML-страница для Web-ошибок приложения.
`favicon.ico`	Иконка приложения.
`robots.txt`	Настройки индексации для поисковых роботов.
`sitemap.xml`	Карта сайта.
`composer.json`	Корневой Composer-файл проекта.
`composer.lock`	Зафиксированные версии установленных Composer-пакетов.
`vendor/`	Установленные Composer-пакеты.
`package.json`	Корневой npm-файл проекта.
`package-lock.json`	Зафиксированные версии установленных npm-пакетов.
`node_modules/`	Установленные npm-пакеты.
`vite.config.js`	Конфигурация Vite-сборки для frontend-слоя.
`frontend/`	Исходники frontend-слоя: Twig-шаблоны, Vue-компоненты и shared-утилиты.
`build/`	Результат Vite-сборки (CSS/JS/изображения, шрифты и `.vite/manifest.json`).
`medusa/`	Основной код ядра фреймворка. Важно: пользовательские файлы в этом каталоге не создаются.
`config/`	Конфигурационные файлы.
`routes/`	Web- и API-маршруты.
`cache/`	Каталог кеша: смонтирован из `.volumes/cache/`
`storage/`	Локальное хранилище файлов приложения: смонтирован из `.volumes/storage/`, а при изменении параметра `STORAGE_ROOT_PATH` mount-путь меняется вместе с ним.
`logs/`	Логи приложения: смонтирован из `.volumes/logs/`.

Каталог www/medusa/

Объект	Назначение
Start/
`Loader.php`	Регистрация автозагрузчика классов.
Base/
`Abstracts/Response.php`	Базовый абстрактный класс для типов HTTP-ответов.
`Interfaces/Resource.php`	Интерфейс для контроллеров с CRUD-методами.
`Interfaces/ServerUrl.php`	Контракт для работы с серверным URL.
`Traits/SecurePassword.php`	Внутренний трейт для хеширования и проверки паролей.
Http/
`Server.php`	Работа с адресом текущего запроса.
`Request.php`	Работа с входящим HTTP-запросом.
`Response.php`	Формирование HTTP-ответа.
`Response/Html.php` `Response/JsonResult.php` `Response/JsonError.php`	Типы ответов для HTML и JSON-ответов.
`Route.php`	Работа с Web-маршрутами.
`Api.php`	Работа с API-маршрутами.
`Client/Curl.php`	HTTP-клиент на базе cURL.
`Cookie.php`	Работа с cookie.
`Session.php`	Работа с сессиями.
Helpers/
`Code.php`	Генератор числовых кодов по маске.
`Hash.php`	Генератор строковых хешей.
`Uuid.php`	Генератор UUID версии 4.
`Token.php`	Генератор токенов.
`Email.php`	Проверка email-адресов, фейковых доменов и чтение значения адреса.
`Phone.php`	Подготовка телефонных номеров к сохранению и выводу.
`Frontend.php`	Фасад helper-слоя для fluent-работы с Twig- и Vite-подходами.
`Frontend/Twig.php`	Helper-обёртка над TwigView.
`Frontend/Vite.php`	Helper-обёртка над ViteEntry.
DataBase/
`PDO.php`	Расширение стандартного PDO дополнительными возможностями.
Lang/
`Loc.php`	Загрузка и получение локализованных сообщений.
Mail/
`Mail.php`	Формирование и отправка писем.
Queue/
`RabbitMQ.php`	Работа с очередями RabbitMQ.
Storage/
`Directory.php`	Работа с директориями.
`File.php`	Работа с файлами.
`Image.php`	Работа с изображениями.
`Redis.php`	Работа с данными Redis.
Frontend/
`Path.php`	Формирование полного и относительного путей к frontend-исходникам и каталогу сборки.
`ManifestJson.php`	Формирование пути к файлу `.vite/manifest.json` в каталоге сборки.
`TwigView.php`	Рендеринг Twig-шаблонов из одного или нескольких source-каталогов frontend с кешированием в `www/cache/`.
`ViteEntry.php`	Генерация preload/CSS/JS-тегов по manifest и выдача mount/state для Vite entry-приложений из одного или нескольких source-каталогов frontend.
Прочее
`index.php`	Точка входа приложения и инициализация окружения.
`constants.php`	Глобальные константы приложения.
`functions.php`	Подключение базовых и вспомогательных функций из `functions/`.
`functions/`	Набор базовых и вспомогательных функций.
`routes.php`	Объявление системных Web- и API-маршрутов, а также подключение файлов `www/routes/api.php` и `www/routes/web.php`.
`composer.json`	Composer-файл ядра с runtime-зависимостями. Подключается корневым `composer.json` через `wikimedia/composer-merge-plugin`.
`package.json`	npm-файл ядра с runtime-зависимостями frontend. Подключается корневым `package.json` через workspaces.

Каталог www/config/

Объект	Назначение
`app.php`	Базовые параметры приложения и правила автозагрузки классов.
`database.php`	Настройки и параметры подключения к базе данных.
`mail.php`	Параметры отправки электронной почты.
`storage.php`	Параметры локального файлового хранилища и Redis-сервера.
`queue.php`	Параметры подключения к RabbitMQ-серверу.
`frontend.json`	Параметры frontend-слоя: source-каталоги, каталог сборки и Vite-алиасы.

Каталог www/routes/

Объект	Назначение
`api.php`	Объявление API-маршрутов.
`web.php`	Объявление Web-маршрутов.