# AIDB Backend API Canon

## Статус

Статус: Stage 5 backend architecture canon draft.

Дата: 2026-05-20.

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

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

## 1. Назначение

Этот canon закрывает:

- общую backend-структуру;
- модульную карту API;
- границы backend domains;
- правило, что нельзя делать один большой routes-файл;
- public/workspace/internal API boundaries;
- API совместимость и версионирование.

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

`system/backend/` - это системная backend-зона AIDB.

Она хранит:

- HTTP entrypoints;
- domain modules;
- backend services;
- API contracts;
- shared backend helpers;
- orchestration logic между backend modules.

`system/backend/` не хранит:

- client-owned files;
- storefront pages конкретного владельца;
- runtime temp files;
- локальный инвентарь business-owner сущностей.

Для этого существуют:

- `children/`;
- `system/runtime/`;
- `system/database/`.

## 3. Каноническая backend-структура

```text
system/backend/
  entrypoints/
    public/
    workspace/
    internal/
  modules/
    shell/
    gate/
    appmarket/
    applications/
    contours/
    users/
    employees/
    rbac/
    storefront/
    publication/
    personal-cabinet/
    supplier-offers/
    client-requests/
    intercompany/
  services/
  contracts/
  shared/
```

Эта структура является канонической верхнеуровневой backend map.

Названия файлов внутри модулей могут отличаться, но границы доменов должны сохраняться.

## 4. Entry surfaces

Backend AIDB должен различать три входные поверхности:

### 4.1. Public

`entrypoints/public/`

Это внешняя API-поверхность для:

- public storefront;
- public publication pages;
- client request entry;
- supplier proposal entry, если маршрут разрешен;
- публичных form actions;
- public metadata, если она разрешена.

### 4.2. Workspace

`entrypoints/workspace/`

Это внутренняя owner/staff API-поверхность для:

- Shell;
- Gate после входа;
- AppMarket;
- business-center/business-level/business-contour workspaces;
- staff actions;
- RBAC-driven actions;
- internal review and management flows.

### 4.3. Internal

`entrypoints/internal/`

Это внутренняя системная API-поверхность для:

- worker callbacks;
- runtime orchestration;
- internal service communication;
- health checks;
- import/export control hooks;
- internal processing endpoints.

`internal` не должен становиться внешним public API.

## 5. Модульное правило

Запрещено:

- один большой `routes.py` для всего проекта;
- один giant controller для всех доменов;
- смешивание unrelated endpoints в одном модуле;
- хранение domain logic только в entrypoint-файле.

Каждый backend domain должен жить в своем модуле.

Минимальный принцип:

- entrypoint принимает запрос;
- backend module владеет domain routes;
- service layer выносит общую backend-логику;
- contracts фиксируют внешние и внутренние API ожидания.

## 6. Обязательные backend modules

### 6.1. Shell API

Путь:

`system/backend/modules/shell/`

Закрывает:

- workspace bootstrap;
- current contour context;
- navigation tree;
- shell-visible modules list;
- language/theme bootstrap data;
- owner/staff workspace metadata.

Не закрывает:

- login;
- public storefront;
- AppMarket install flow;
- personal cabinet.

### 6.2. Gate API

Путь:

`system/backend/modules/gate/`

Закрывает:

- login;
- registration;
- verification;
- password recovery;
- session bootstrap;
- pre-shell access checks.

### 6.3. AppMarket API

Путь:

`system/backend/modules/appmarket/`

Закрывает:

- catalog listing;
- install availability;
- install permissions;
- app cards;
- contour cards;
- trial/subscription availability display;
- install requests.

Не закрывает:

- public storefront catalog;
- customer orders;
- publication of goods/services.

### 6.4. Applications API

Путь:

`system/backend/modules/applications/`

Закрывает:

- built-in app metadata;
- app activation state;
- app instance discovery;
- app settings handoff;
- app-open context bootstrap.

### 6.5. Business Contours API

Путь:

`system/backend/modules/contours/`

Закрывает:

- contour package metadata;
- contour install/open/manage flows;
- contour instance bootstrap;
- contour-specific visibility and ownership context.

### 6.6. Users API

Путь:

`system/backend/modules/users/`

Закрывает:

- user identity;
- profile core fields;
- account states;
- base user links.

### 6.7. Employees API

Путь:

`system/backend/modules/employees/`

Закрывает:

- employee assignments;
- contour-bound employee records;
- staff profiles inside business spaces;
- employee visibility by contour.

### 6.8. RBAC API

Путь:

`system/backend/modules/rbac/`

Закрывает:

- roles;
- role assignments;
- permission scopes;
- current contour checks;
- rights evaluation;
- action visibility rules.

`RBAC` не смешивается с employee catalog CRUD в одном домене только потому, что они связаны.

### 6.9. Storefront API

Путь:

`system/backend/modules/storefront/`

Закрывает:

- storefront pages;
- storefront routing metadata;
- storefront page visibility;
- storefront owner binding;
- storefront page loading for public surfaces.

### 6.10. Publication API

Путь:

`system/backend/modules/publication/`

Закрывает:

- `publication_view`;
- publication create/update/unpublish flow;
- publication ownership;
- publication visibility status;
- publication link to internal card and proposal.

### 6.11. Personal Cabinet API

Путь:

`system/backend/modules/personal-cabinet/`

Закрывает:

- client cabinet surface;
- supplier cabinet surface;
- representative cabinet surface;
- cabinet dashboard/context data;
- cabinet-visible actions.

### 6.12. Supplier Offers API

Путь:

`system/backend/modules/supplier-offers/`

Закрывает:

- supplier commercial proposal intake;
- proposal submission;
- proposal update/withdraw flows;
- proposal statuses for supplier;
- direct or centralized routing to allowed target contour.

### 6.13. Client Offers / Requests API

Путь:

`system/backend/modules/client-requests/`

Закрывает:

- client incoming requests;
- client proposal/request flows from storefront;
- request-to-publication linkage;
- request statuses;
- handoff to sales/review logic.

### 6.14. Intercompany API

Путь:

`system/backend/modules/intercompany/`

Закрывает:

- intercompany relations;
- owner/counterparty links;
- supplier/client relation logic;
- representative/commission relation logic;
- internal executor links;
- relation history metadata.

## 7. Shared backend services

Путь:

`system/backend/services/`

Здесь живут только переиспользуемые backend services:

- auth helpers;
- validation helpers;
- rate limiting helpers;
- pagination helpers;
- audit log emitters;
- backend-side mappers;
- access orchestration helpers.

`services/` не должна превращаться в вторую свалку доменной логики.

Если логика принадлежит одному домену, она остается внутри его backend module.

## 8. Contracts

Путь:

`system/backend/contracts/`

Тут фиксируются:

- API request/response expectations;
- module boundaries;
- visibility rules;
- public/internal contract notes;
- versioning rules;
- compatibility expectations for developer and auditor.

Критические backend договоренности не должны жить только в чате.

## 9. API versioning and compatibility

AIDB должен использовать явную API version surface.

Каноническое правило:

- одна активная основная API версия, например `v1`;
- breaking changes идут через новую версию, например `v2`;
- additive changes внутри версии разрешены, если не ломают текущих клиентов;
- временные debug/test routes не являются каноном.

Правила совместимости:

- не удалять обязательное поле без новой версии;
- не менять смысл поля silently;
- не переносить endpoint между доменами без явной migration note;
- не смешивать public и workspace payload semantics в одном route без необходимости.

## 10. Public and workspace boundary

Нужно жестко разделять:

- public storefront API;
- workspace staff API;
- personal cabinet API;
- internal runtime API.

Один endpoint не должен одновременно быть:

- public customer endpoint;
- owner workspace management endpoint;
- internal worker control endpoint.

Если смысл разный, route group должен быть разный.

## 11. Что нельзя делать

Запрещено:

- один giant routes file на весь проект;
- appmarket и storefront в одном backend module;
- publication и raw supplier proposal как одну и ту же сущность;
- shell bootstrap и login logic в одном domain module;
- personal cabinet и staff workspace как одну и ту же API-поверхность;
- intercompany history хранить только в файловых артефактах;
- создавать отдельную backend mini-architecture внутри каждого app без общей канонической map.

## 12. Что не входит в этот документ

Этот document не фиксирует:

- точные URL path names;
- database schema;
- worker implementation;
- notification transport;
- payment provider;
- search engine implementation;
- actual code layout внутри конкретного языка/framework.

Эти зоны закрываются в следующих technical documents или implementation stages.

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

Backend/API архитектура считается закрытой для Stage 5, если:

- `system/backend/` разделен на entrypoints, modules, services, contracts и shared;
- giant routes file запрещен;
- обязательные backend domains перечислены;
- public/workspace/internal boundaries зафиксированы;
- AppMarket, storefront, publication, personal-cabinet и intercompany разведены;
- есть правило версии и совместимости API;
- developer не должен сам придумывать backend map с нуля.