crank/docs/architecture.md

Архитектура

Crank Community публикует REST API как MCP tools.

Сервисы

• ui — web-интерфейс.
• admin-api — HTTP API для авторизации, operations, agents, secrets, logs и settings.
• mcp-server — MCP Streamable HTTP endpoint для published agents.

Основные сущности

• Workspace — граница данных.
• Operation — REST integration contract.
• Agent — опубликованный MCP surface с ограниченным набором tools.
• Secret и AuthProfile — безопасное применение upstream credentials.
• InvocationLog и UsageRollup — observability.

Flow

1. Пользователь создает REST operation.
2. Пользователь настраивает target, schemas и mapping.
3. admin-api сохраняет draft и version.
4. Runtime выполняет test call через REST adapter.
5. Пользователь публикует operation.
6. Пользователь привязывает operation к agent.
7. mcp-server открывает published operation как MCP tool.

Runtime path

MCP client
  -> mcp-server
  -> crank-runtime
  -> crank-adapter-rest
  -> upstream REST API

Input mapping переводит MCP arguments в REST request. Output mapping переводит REST response в MCP tool result.

Rust boundaries

В Community-коде закреплены следующие границы:

• crank-core::domain — доменные типы: operations, agents, users, secrets, observability, ids.
• crank-core::ports — интерфейсы внешних зависимостей: policy, audit, identity, protocol adapters, cache stores, metering.
• crank-registry::records — read/write records, которые возвращает storage layer.
• crank-registry::requests — request-структуры для persistence операций.
• crank-registry::infrastructure — PostgreSQL registry facade, pool config и extension migrations.
• apps/admin-api/src/dto.rs — HTTP payloads и view models. Service layer не должен владеть DTO-типами.
• apps/admin-api/src/service/* — application use-cases. Эти модули не импортируют axum.
• crates/crank-community-mcp/src/transport.rs — MCP Streamable HTTP transport: headers, accept negotiation, session id, JSON/SSE responses.
• RuntimeExecutionRequest — единая точка расширения runtime execution parameters. Новые auth/context/cache/metring параметры добавляются туда, а не через новые execute_with_* методы.

Границы проверяются скриптами:

scripts/check-rust-boundaries.sh
scripts/check-rust-module-boundaries.sh
scripts/check-rust-code-health.sh

Хранилище

PostgreSQL хранит:

• users и sessions;
• workspaces;
• operations и versions;
• agents и bindings;
• secrets и auth profiles;
• logs и usage.

Файловое хранилище используется для samples и YAML import payloads.