crank/docs/diagrams.md

Диаграммы

1. Назначение документа

Этот документ собирает диаграммы целевой модели проекта:

• компонентную структуру;
• связи между доменными сущностями;
• хранение данных в БД.

Примечание:

• диаграммы требуют следующего обновления по слою машинного доступа;
• вместо PlatformApiKey целевая модель проекта теперь использует AgentKey, IssuedAgentToken и при необходимости PlatformClientCredential;
• детальная схема зафиксирована в docs/agent-auth-model.md.

2. Компонентная диаграмма

flowchart LR
    UI[crank-ui]
    ADMIN[admin-api]
    MCP[mcp-server]
    REG[crank-registry]
    RUN[crank-runtime]
    CORE[crank-core]
    SCHEMA[crank-schema]
    MAP[crank-mapping]
    REST[adapter-rest]
    DB[(PostgreSQL)]
    STORE[(Artifact Storage)]
    OBS[(Usage and Logs)]

    UI --> ADMIN
    MCP --> REG
    MCP --> RUN
    ADMIN --> REG
    ADMIN --> RUN
    REG --> DB
    REG --> CORE
    REG --> SCHEMA
    REG --> MAP
    RUN --> CORE
    RUN --> SCHEMA
    RUN --> MAP
    RUN --> REST
    ADMIN --> STORE
    REG --> OBS
    ADMIN --> OBS

3. Структурная диаграмма доменной модели

classDiagram
    class Workspace {
      +id
      +slug
      +display_name
    }

    class Operation {
      +id
      +workspace_id
      +name
      +display_name
      +protocol
      +status
    }

    class Agent {
      +id
      +workspace_id
      +slug
      +display_name
      +status
    }

    class AgentBinding {
      +operation_id
      +operation_version
      +tool_name
      +enabled
    }

    class PlatformApiKey {
      +id
      +workspace_id
      +name
      +prefix
      +scopes
      +status
    }

    class InvocationLog {
      +workspace_id
      +agent_id
      +operation_id
      +status
      +duration_ms
    }

    Workspace --> Operation : owns
    Workspace --> Agent : owns
    Workspace --> PlatformApiKey : owns
    Agent --> AgentBinding : contains
    AgentBinding --> Operation : references
    InvocationLog --> Workspace : belongs_to
    InvocationLog --> Agent : belongs_to
    InvocationLog --> Operation : belongs_to

4. ER-диаграмма БД

erDiagram
    WORKSPACES ||--o{ OPERATIONS : owns
    WORKSPACES ||--o{ AGENTS : owns
    WORKSPACES ||--o{ AUTH_PROFILES : owns
    WORKSPACES ||--o{ PLATFORM_API_KEYS : owns
    WORKSPACES ||--o{ INVOCATION_LOGS : owns
    OPERATIONS ||--o{ OPERATION_VERSIONS : has
    OPERATIONS ||--o| PUBLISHED_OPERATIONS : publishes
    AGENTS ||--o{ AGENT_VERSIONS : has
    AGENTS ||--o| PUBLISHED_AGENTS : publishes
    AGENT_VERSIONS ||--o{ AGENT_OPERATION_BINDINGS : contains
    OPERATIONS ||--o{ AGENT_OPERATION_BINDINGS : exposed_by

    WORKSPACES {
      text id PK
      text slug
      text display_name
    }
    OPERATIONS {
      text id PK
      text workspace_id FK
      text name
      text display_name
      text protocol
      text status
    }
    AGENTS {
      text id PK
      text workspace_id FK
      text slug
      text display_name
      text status
    }