# AIDB System Structure Canon

## Статус

Статус: active system structure canon.

Дата: 2026-05-20.

Этот документ фиксирует каноническую структуру `system/` в проекте AIDB.

## 1. Главный принцип

`system/` хранит системный код, системные пакеты, системные шаблоны, системные contracts и системные правила.

`system/` не хранит клиентский инвентарь, клиентские документы, клиентские storefront pages и локальные данные конкретного бизнеса.

Для этого существует `children/`.

## 2. Каноническая структура system

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

Эти зоны являются канонической верхнеуровневой структурой `system/`.

## 3. Shell

Путь:

`system/shell/`

`Shell` - это системный рабочий каркас платформы.

В `Shell` входят:

- верхняя панель;
- навигация;
- левое меню;
- рабочая область;
- открытие карточек;
- открытие приложений;
- открытие бизнес-контуров;
- глобальные действия;
- language/theme switching;
- current contour routing;
- базовая orchestration-логика рабочей среды.

В `Shell` не входят:

- login;
- registration;
- password reset;
- бизнес-логика приложений;
- бизнес-логика бизнес-контуров;
- клиентские данные;
- торговые данные;
- intercompany;
- supplier/client cabinet logic.

Минимальный пакет `Shell`:

```text
system/shell/
  interface.html
  logic.js
  manifest.json
  settings.json
  texts.json
  README.md
  developer.md
  contracts/
```

## 4. Gate

Путь:

`system/gate/`

`Gate` - это входной пакет до рабочей среды.

В `Gate` входят:

- login;
- registration;
- invite and verification flows;
- password reset;
- session bootstrap;
- входная проверка доступа;
- pre-shell flows.

`Gate` не превращается в mini-shell.

Минимальный пакет `Gate`:

```text
system/gate/
  interface.html
  logic.js
  manifest.json
  settings.json
  texts.json
  README.md
  developer.md
  contracts/
```

## 5. AppMarket

Путь:

`system/appmarket/`

`AppMarket` - это внутренний market установки расширений.

В него входят:

- catalog UI;
- install flows;
- app cards;
- contour cards;
- availability display;
- install permissions;
- trial/subscription display rules;
- appmarket docs and contracts.

`AppMarket` не является внешней торговой витриной.

Минимальный пакет:

```text
system/appmarket/
  interface.html
  logic.js
  manifest.json
  settings.json
  texts.json
  README.md
  developer.md
  contracts/
```

## 6. Applications

Путь:

`system/applications/`

Это встроенные системные приложения.

Примеры:

- messages;
- tasks;
- calendar;
- documents;
- profile;
- settings;
- administration;
- management;
- personal-cabinet;
- позже mail.

Каждое приложение живет в своей отдельной папке:

```text
system/applications/<app_code>/
  interface.html
  logic.js
  manifest.json
  settings.json
  texts.json
  README.md
  developer.md
  user-guide.md
  contracts/
```

## 7. Contours

Путь:

`system/contours/`

Это installable business contour packages.

Каждый контур живет в своей отдельной системной папке:

```text
system/contours/<business_contour_code>/
  interface.html
  logic.js
  manifest.json
  settings.json
  texts.json
  README.md
  developer.md
  user-guide.md
  contracts/
```

Тут хранится системный шаблон контура, а не клиентский установленный экземпляр.

## 8. Storefront

Путь:

`system/storefront/`

Это системная зона storefront-движков и системных шаблонов публикации.

Здесь живут:

- storefront engines;
- storefront contracts;
- storefront templates;
- publication helpers;
- rendering rules;
- системные storefront assets.

Конкретные страницы конкретного клиента здесь не живут.

Они живут в `children/` у владельца.

## 9. Backend

Путь:

`system/backend/`

Это системный backend AIDB.

Рекомендуемая структура:

```text
system/backend/
  modules/
  services/
  shared/
  entrypoints/
```

Минимально backend должен быть модульным по доменам:

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

Не строить один большой общий route-файл как основу архитектуры.

## 10. Database

Путь:

`system/database/`

Это системная зона database-структуры.

Рекомендуемая структура:

```text
system/database/
  config/
  migrations/
  schema/
  seeds/
```

Здесь хранятся:

- database config;
- migrations;
- schema/models;
- seed/demo data.

## 11. Runtime

Путь:

`system/runtime/`

Это системная runtime-зона.

Рекомендуемая структура:

```text
system/runtime/
  modules/
  workers/
  schedulers/
  storage/
  contracts/
```

Здесь хранятся:

- runtime contracts;
- workers;
- scheduled jobs;
- upload/download handlers;
- runtime orchestration;
- общие runtime helpers.

## 12. Languages

Путь:

`system/languages/`

Каноническая структура:

```text
system/languages/
  en/
  ru/
  az/
  zh/
  ar/
```

Это централизованная зона языков.

Каждый системный пакет и каждый модуль должен использовать общую language architecture, а не локальный хаотичный словарь.

## 13. Themes

Путь:

`system/themes/`

Здесь живут:

- системные темы;
- theme contracts;
- shared visual tokens;
- theme assets.

## 14. Shared

Путь:

`system/shared/`

Это зона общих ресурсов, которые не принадлежат одному модулю.

Здесь могут жить:

- shared schemas;
- shared contracts;
- shared helpers;
- shared UI assets;
- shared icons;
- shared validation logic.

`shared/` не должен превращаться в свалку всего подряд.

## 15. Что нельзя класть в system

В `system/` нельзя класть:

- клиентские документы;
- клиентские storefront pages;
- клиентские uploads;
- локальный инвентарь конкретного business_center;
- локальный runtime state конкретного клиента;
- данные конкретного поставщика как владельца;
- данные конкретного клиента как владельца.

Все это живет в `children/` и/или в базе.

## 16. Критерий готовности

System structure считается зафиксированной, если:

- каждая системная зона имеет понятную границу;
- Shell и Gate разделены;
- AppMarket и storefront разделены;
- applications и contours разделены;
- backend, database и runtime не смешаны;
- languages и themes централизованы;
- client inventory не попадает в `system/`.