docs: Update docs for the correctness (#13)

2026-04-15 00:48:06 +03:00
1 parent 8dba55272c
commit 51a783f93a
@@ -0,0 +1,45 @@
+---
+title: Архитектура и Философия
+weight: 1
+---
+
+**Цель:** Понять основные принципы проектирования, лежащие в основе модульности Quetza.
+
+## Философия проектирования
+
+### Соглашение важнее конфигурации (Convention Over Configuration)
+
+Quetza минимизирует шаблонный код, полагаясь на строгую структуру папок.
+
+- **Никакого центрального реестра:** Сама файловая система _является_ реестром.
+- **Результат:** Вам не нужно обновлять файл конфигурации, чтобы добавить модуль; вы просто создаете папку.
+
+### Композиция важнее наследования (Composition Over Inheritance)
+
+Модули состоят из возможностей (capabilities), а не наследуются от базового класса.
+
+- **Гибкость:** Модули могут использовать любую внутреннюю архитектуру (Функциональную, ООП), пока они экспортируют необходимые интерфейсы.
+
+### Изоляция важнее интеграции (Isolation Over Integration)
+
+Модули не могут напрямую вызывать друг друга.
+
+- **Почему:** Это предотвращает сильную связность (tight coupling).
+- **Преимущество:** Вы можете удалить любой модуль, не сломав остальную часть бота.
+
+## Основные сущности
+
+| Сущность | Роль | Жизненный цикл |
+| :--- | :--- | :--- |
+| **Client** | Локатор сервисов и оркестратор | Синглтон. Руководит всем. |
+| **Module** | Пространство имен для функций | Загружается при запуске. |
+| **Command** | Конечная точка взаимодействия с пользователем | Без состояния (Stateless). Запрос/Ответ. |
+| **Event** | Реактивный наблюдатель (Observer) | Подписывается при запуске. |
+| **Controller** | Менеджер состояния | Сохраняется между взаимодействиями. |
+
+---
+
+**См. также:**
+
+- [Паттерн Service Locator](https://ru.wikipedia.org/wiki/Локатор_служб)
+- [Паттерн Observer](https://ru.wikipedia.org/wiki/Наблюдатель_(шаблон_проектирования))