crank/docs/diagrams.md

Диаграммы

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

Этот документ собирает диаграммы, которые фиксируют проект до начала разработки:

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

Диаграммы даны в формате Mermaid, чтобы их можно было хранить прямо в репозитории и рендерить в Markdown-compatible tooling.

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

flowchart LR
    UI[mcpaas-ui]
    ADMIN[admin-api]
    MCP[mcp-server]
    REG[mcpaas-registry]
    RUN[mcpaas-runtime]
    CORE[mcpaas-core]
    SCHEMA[mcpaas-schema]
    MAP[mcpaas-mapping]
    PROTO[mcpaas-proto]
    REST[adapter-rest]
    GQL[adapter-graphql]
    GRPC[adapter-grpc]
    DB[(PostgreSQL)]
    STORE[(Artifact Storage)]

    UI --> ADMIN
    MCP --> REG
    MCP --> RUN
    ADMIN --> REG
    ADMIN --> RUN
    ADMIN --> PROTO

    REG --> DB
    REG --> CORE
    REG --> SCHEMA
    REG --> MAP

    RUN --> CORE
    RUN --> SCHEMA
    RUN --> MAP
    RUN --> REST
    RUN --> GQL
    RUN --> GRPC

    GRPC --> PROTO
    PROTO --> STORE
    ADMIN --> STORE

3. Диаграмма зависимостей crates

flowchart TD
    CORE[mcpaas-core]
    SCHEMA[mcpaas-schema]
    MAP[mcpaas-mapping]
    PROTO[mcpaas-proto]
    REG[mcpaas-registry]
    RUN[mcpaas-runtime]
    REST[mcpaas-adapter-rest]
    GQL[mcpaas-adapter-graphql]
    GRPC[mcpaas-adapter-grpc]
    ADMIN[apps/admin-api]
    MCP[apps/mcp-server]

    SCHEMA --> CORE
    MAP --> CORE
    PROTO --> CORE
    PROTO --> SCHEMA
    REG --> CORE
    REG --> SCHEMA
    REG --> MAP
    REST --> CORE
    GQL --> CORE
    GRPC --> CORE
    GRPC --> PROTO
    RUN --> CORE
    RUN --> SCHEMA
    RUN --> MAP
    RUN --> REST
    RUN --> GQL
    RUN --> GRPC
    ADMIN --> CORE
    ADMIN --> SCHEMA
    ADMIN --> MAP
    ADMIN --> PROTO
    ADMIN --> REG
    ADMIN --> RUN
    MCP --> CORE
    MCP --> REG
    MCP --> RUN

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

classDiagram
    class Operation {
      +id
      +name
      +display_name
      +protocol
      +status
      +version
      +target
      +input_schema
      +output_schema
      +input_mapping
      +output_mapping
      +execution_config
      +tool_description
      +samples
      +generated_draft
      +config_export
    }

    class RestTarget {
      +base_url
      +method
      +path_template
      +static_headers
    }

    class GraphqlTarget {
      +endpoint
      +operation_type
      +operation_name
      +query_template
      +response_path
    }

    class GrpcTarget {
      +server_addr
      +package
      +service
      +method
      +descriptor_ref
      +descriptor_set_b64
    }

    class Schema {
      +type
      +description
      +fields
    }

    class MappingSet {
      +rules[]
    }

    class MappingRule {
      +source
      +target
      +required
      +default_value
      +transform
      +condition
    }

    class ExecutionConfig {
      +timeout_ms
      +retry_policy
      +auth_profile_ref
      +headers
      +protocol_options
    }

    class AuthProfile {
      +id
      +name
      +kind
      +config
    }

    class ToolDescription {
      +title
      +description
      +tags
      +examples
    }

    class Samples {
      +input_json_sample_ref
      +output_json_sample_ref
      +proto_file_ref
      +descriptor_ref
    }

    class GeneratedDraft {
      +status
      +source_types
      +generated_at
      +warnings
    }

    Operation --> RestTarget : target
    Operation --> GraphqlTarget : target
    Operation --> GrpcTarget : target
    Operation --> Schema : input_schema
    Operation --> Schema : output_schema
    Operation --> MappingSet : input_mapping
    Operation --> MappingSet : output_mapping
    Operation --> ExecutionConfig : execution_config
    Operation --> ToolDescription : tool_description
    Operation --> Samples : samples
    Operation --> GeneratedDraft : generated_draft
    ExecutionConfig --> AuthProfile : auth_profile_ref
    MappingSet --> MappingRule : contains

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

erDiagram
    OPERATIONS ||--o{ OPERATION_VERSIONS : has
    OPERATIONS ||--o| PUBLISHED_OPERATIONS : publishes
    OPERATIONS ||--o{ OPERATION_SAMPLES : owns
    OPERATIONS ||--o{ DESCRIPTORS : may_use
    OPERATIONS ||--o{ YAML_IMPORT_JOBS : may_create
    AUTH_PROFILES ||--o{ OPERATION_VERSIONS : referenced_by

    OPERATIONS {
      text id PK
      text name
      text display_name
      text protocol
      text status
      int current_draft_version
      int latest_published_version
      timestamptz created_at
      timestamptz updated_at
      timestamptz published_at
    }

    OPERATION_VERSIONS {
      text operation_id FK
      int version
      text status
      jsonb target_json
      jsonb input_schema_json
      jsonb output_schema_json
      jsonb input_mapping_json
      jsonb output_mapping_json
      jsonb execution_config_json
      jsonb tool_description_json
      jsonb samples_json
      jsonb generated_draft_json
      jsonb config_export_json
      timestamptz created_at
    }

    PUBLISHED_OPERATIONS {
      text operation_id PK
      int version
      timestamptz published_at
      text published_by
    }

    OPERATION_SAMPLES {
      text id PK
      text operation_id FK
      int version
      text sample_kind
      text storage_ref
      text content_type
      text file_name
      timestamptz created_at
    }

    DESCRIPTORS {
      text id PK
      text operation_id FK
      int version
      text descriptor_kind
      text storage_ref
      jsonb package_index_json
      timestamptz created_at
    }

    YAML_IMPORT_JOBS {
      text id PK
      text source_sample_id
      text status
      text format_version
      text mode
      text result_operation_id
      int result_version
      text error_text
      timestamptz created_at
      timestamptz finished_at
    }

    AUTH_PROFILES {
      text id PK
      text name
      text kind
      jsonb config_json
      timestamptz created_at
      timestamptz updated_at
    }

6. Sequence: создание и публикация operation

sequenceDiagram
    participant UI
    participant API as admin-api
    participant REG as registry
    participant RUN as runtime
    participant MCP as mcp-server

    UI->>API: POST /operations
    API->>REG: create operation v1
    REG-->>API: created
    API-->>UI: operation_id, version

    UI->>API: upload samples / descriptors
    API-->>UI: artifact refs

    UI->>API: POST /drafts/generate
    API->>REG: save generated draft metadata
    API-->>UI: generated draft

    UI->>API: POST /test-runs
    API->>RUN: execute draft version
    RUN-->>API: request_preview + response_preview
    API-->>UI: test result

    UI->>API: POST /publish
    API->>REG: mark version as published
    REG-->>API: published
    API-->>MCP: reload signal
    API-->>UI: published_version

7. Sequence: MCP tool execution

sequenceDiagram
    participant Client as MCP Client
    participant MCP as mcp-server
    participant REG as registry/cache
    participant RUN as runtime
    participant ADP as protocol adapter

    Client->>MCP: call tool(name, input)
    MCP->>REG: resolve published runtime view
    REG-->>MCP: runtime operation
    MCP->>RUN: execute(operation, input)
    RUN->>RUN: validate input schema
    RUN->>RUN: apply input mapping
    RUN->>ADP: execute prepared request
    ADP-->>RUN: normalized response
    RUN->>RUN: apply output mapping
    RUN-->>MCP: output
    MCP-->>Client: tool result

8. Sequence: YAML import

sequenceDiagram
    participant UI
    participant API as admin-api
    participant REG as registry

    UI->>API: POST /operations/import (YAML)
    API->>API: parse YAML
    API->>API: validate schema, target, mapping
    API->>REG: create or upsert new version
    REG-->>API: operation_id, version
    API-->>UI: import result

9. Что важно помнить

• Диаграммы фиксируют целевую архитектуру, а не точную реализацию каждого файла.
• Если меняется модель данных или поток исполнения, сначала нужно обновлять документы, потом код.
• Для старта разработки этого набора достаточно: компоненты, сущности, БД и ключевые sequence flows уже описаны.