# AIDB Architect Scope

## Статус

Статус: active architect scope for new project start.

Дата: 2026-05-20.

Этот документ определяет, что именно должен спроектировать новый архитектор AIDB.

Он не описывает реализацию кода.

Он описывает обязательный архитектурный пакет, без которого разработка не должна разрастаться.

## 1. Роль архитектора AIDB

Новый архитектор AIDB отвечает за:

- сбор полного архитектурного пакета нового проекта;
- закрепление терминов и границ сущностей;
- проектирование корневой структуры проекта;
- проектирование `system/`, `docs/`, `children/`;
- проектирование backend/API, runtime, database и storage map;
- проектирование моделей карточек, коммерческих предложений, публикации, личных кабинетов и intercompany;
- устранение двусмысленностей до старта большой реализации.

Архитектор не должен начинать с произвольной реализации кода до завершения архитектурного пакета.

## 2. Что уже считается утвержденной базой

Архитектор обязан использовать как основу:

- [AIDB_FOUNDATION_CANON.md](/home/elmar/aidb/docs/AIDB_FOUNDATION_CANON.md:1)

Этот документ уже фиксирует:

- иерархию AIDB;
- новые термины;
- роль платформы;
- роль бизнес-центра;
- роль бизнес-уровня;
- AppMarket;
- витрину;
- карточки;
- коммерческие предложения;
- централизованный прием предложений;
- личные кабинеты;
- intercompany;
- базовое разделение хранения.

## 3. Что архитектор обязан спроектировать

Архитектор обязан вернуть полную архитектуру по следующим большим блокам.

### 3.1. Корень проекта

Нужно утвердить:

- окончательный root map `/home/elmar/aidb/`;
- нужны ли дополнительные корневые папки;
- что строго запрещено выносить в отдельный корень;
- что остается только внутри `system/`, `docs/`, `children/`.

### 3.2. System map

Нужно утвердить структуру:

- `system/shell/`
- `system/gate/`
- `system/appmarket/`
- `system/applications/`
- `system/contours/`
- `system/storefront/`
- `system/backend/`
- `system/database/`
- `system/runtime/`
- `system/languages/`
- `system/themes/`
- `system/shared/`

Для каждой зоны нужно зафиксировать:

- что туда входит;
- что туда не входит;
- какие файлы обязательны;
- какие документы обязательны;
- какие runtime/API contracts обязательны.

### 3.3. Children map

Нужно утвердить:

- иерархию `children/`;
- когда папка создается всегда;
- когда папка создается только при локальном инвентаре;
- где живут storefront pages;
- где живут uploads;
- где живут runtime files;
- как дробить клиентский инвентарь при росте данных.

### 3.4. Card architecture

Нужно утвердить:

- единый канон карточки;
- типы сущностей, использующих карточку;
- какие поля обязательны;
- что считается внутренним паспортом;
- как работает публикация карточки;
- как карточка используется как коммерческое предложение;
- когда создается отдельный публикационный вид карточки.

### 3.5. Commercial proposal architecture

Нужно утвердить:

- поток коммерческого предложения;
- источники предложений;
- целевой контур предложения;
- правило `central_offer_intake_enabled`;
- кто создает внешний публикационный вид;
- как связываются материнская карточка и публикационный вид;
- как заказы возвращаются к источнику.

### 3.6. Storefront architecture

Нужно утвердить:

- одно каноническое имя внешней торговой поверхности;
- где проходит граница между AppMarket и storefront;
- как публикуются карточки;
- как публикуются товары и услуги;
- как работает business-center storefront;
- как работает personal storefront на business-level;
- как хранить несколько публичных страниц одной сущности.

### 3.7. Personal cabinet architecture

Нужно утвердить:

- общий модуль `personal-cabinet`;
- ролевые поверхности:
  - client
  - supplier
  - representative
- различие прав и данных;
- история;
- предложения;
- документы;
- финансовую логику представителя.

### 3.8. Intercompany architecture

Нужно утвердить:

- какие связи считаются intercompany;
- кто может быть поставщиком;
- кто может быть клиентом;
- кто может быть внутренним исполнителем;
- кто может быть внешним участником;
- где живут supplier/client offers;
- как хранится история отношений;
- как устроены комиссии.

### 3.9. Backend/API architecture

Нужно утвердить модульную карту API:

- shell;
- gate;
- appmarket;
- applications;
- business contours;
- employees/RBAC;
- cards;
- commercial proposals;
- storefront/public pages;
- personal cabinet;
- intercompany.

Для каждой зоны нужно определить:

- модуль;
- входные routes;
- boundary;
- зависимости;
- запрещенные смешения.

### 3.10. Runtime architecture

Нужно утвердить:

- runtime contracts;
- live runtime state;
- queues;
- workers;
- scheduled jobs;
- upload/download handlers;
- разделение `system runtime` и `children runtime`.

### 3.11. Database architecture

Нужно утвердить:

- database config;
- migrations;
- schema/models;
- seed/demo data;
- что является структурной правдой в базе;
- что не должно жить в базе;
- границу между базой и `children`.

## 4. Что архитектор не должен делать

Архитектор не должен:

- тащить старые публичные термины;
- копировать старую структуру проекта как новую норму;
- начинать с большого кода без пакета архитектуры;
- смешивать AppMarket и storefront;
- смешивать Shell и Gate;
- смешивать system code и client inventory;
- проектировать новую систему вокруг старых компромиссов.

## 5. Обязательный пакет документов

Архитектор должен вернуть как минимум:

- `AIDB_SYSTEM_STRUCTURE_CANON.md`
- `AIDB_CHILDREN_STRUCTURE_CANON.md`
- `AIDB_BACKEND_API_CANON.md`
- `AIDB_RUNTIME_STORAGE_CANON.md`
- `AIDB_STOREFRONT_AND_PUBLICATION_CANON.md`
- `AIDB_PERSONAL_CABINET_AND_INTERCOMPANY_CANON.md`

Если по ходу работы появятся крупные спорные зоны, они должны фиксироваться в отдельных документах, а не растворяться в чате.

## 6. Критерий готовности архитектора

Архитектурный этап считается готовым, если:

- новый проект можно понять без ссылок на старый проект;
- все главные системные зоны имеют фиксированную структуру;
- `system/` и `children/` разведены;
- AppMarket и storefront разведены;
- карточка и коммерческое предложение описаны единообразно;
- personal-cabinet и intercompany не оставлены "на потом";
- backend/API и runtime не остаются в виде абстрактных обещаний;
- developer может начать skeleton без самостоятельного додумывания архитектуры.