AIDB Dev Center

Readable architecture document

AIDB Backend API Canon

Модульная backend/API карта и границы public/workspace/internal entrypoints.

draftsource: AIDB_BACKEND_API_CANON.md

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-структура

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 enable/update/unpublish flow;
  • publication ownership;
  • publication visibility status;
  • publication link to the same card and proposal mode.

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 с нуля.