crank/docs/architecture.md

Архитектура

1. Назначение проекта

Crank - платформа для публикации внешних API в виде MCP tools без написания отдельного backend-кода под каждую интеграцию. Пользователь конфигурирует интеграции через UI, а система:

• хранит и версионирует операции;
• группирует их по workspace;
• публикует их в составе конкретных agents;
• выдает LLM не глобальный каталог tools, а curated toolset на один agent;
• собирает продуктовые логи и usage по workspace, agent и operation.

2. Переход As Is -> To Be

2.1. As Is

Текущее ядро системы построено вокруг:

• глобальной сущности Operation;
• registry версий операций;
• runtime adapters REST / GraphQL / unary gRPC;
• admin-api для CRUD и тестовых вызовов;
• mcp-server, который публикует tools из published operations.

2.2. To Be

Целевая архитектура расширяет текущее ядро до модели:

• Workspace - tenant boundary;
• Operation - интеграционный контракт;
• Agent - curated MCP surface;
• Platform API key и Membership - доступ к самой платформе;
• Invocation log и Usage rollup - observability слой.

Operation остается фундаментом интеграции, но tools больше не публикуются глобально. MCP публикует tools в контексте конкретного workspace и конкретного agent.

3. Ключевые сущности и их роль

Workspace

Изолирует:

• операции;
• auth profiles;
• agents;
• platform API keys;
• logs и usage;
• пользователей и роли.

Operation

Описывает один вызываемый элемент независимо от протокола:

• name
• display_name
• protocol
• target
• input_schema
• input_mapping
• execution_config
• output_mapping
• tool_description
• status

Agent

Является пользовательской MCP-поверхностью для LLM.

Agent:

• принадлежит одному workspace;
• имеет slug, display_name, description, status;
• ссылается на ограниченный набор published operations;
• формирует отдельный MCP endpoint;
• решает проблему "одному агенту нельзя отдавать 100 tools сразу".

Platform access

Отдельный слой, не связанный с upstream auth:

• User
• Membership
• Invitation
• PlatformApiKey

Observability

Отдельный продуктовый слой:

• InvocationLog
• InvocationEvent
• UsageRollup
• LatencyStats

4. Главный принцип проектирования

Система строится в три слоя:

1. Operation как низкоуровневый интеграционный контракт.
2. Agent как curated набор published operations.
3. Workspace как граница данных, доступа и observability.

Это позволяет:

• переиспользовать одну operation в нескольких agents;
• ограничивать tool catalog для конкретного LLM-сценария;
• изолировать данные команд;
• строить logs и usage не глобально, а по tenant boundary.

5. Границы целевого MVP

Входит

• Workspace как tenant boundary.
• Операции REST, GraphQL, unary gRPC.
• Agent и привязка операций к агенту.
• Agent-scoped MCP endpoints.
• Platform API keys.
• Workspace-scoped auth profiles для upstream access.
• Product logs и usage aggregates.
• Импорт и экспорт operation-конфигураций в YAML.
• Hot reload опубликованных agents и operations.

Не входит

• gRPC streaming.
• SOAP.
• Оркестрация workflow.
• Биллинг.
• Full RBAC policy engine.
• Traffic splitting и deployment orchestration.

6. Пользовательские сценарии

Оператор операций

1. Выбирает workspace.
2. Создает или редактирует operation.
3. Выполняет test run.
4. Публикует operation version.
5. Привязывает operation к одному или нескольким agents.

Оператор агентов

1. Создает agent.
2. Выбирает набор published operations.
3. Публикует agent.
4. Получает MCP endpoint вида /mcp/v1/{workspace}/{agent}.

Администратор workspace

1. Управляет API keys платформы.
2. Управляет пользователями и ролями.
3. Смотрит logs и usage.

7. Стратегия по протоколам

REST

• GET
• POST
• PUT
• PATCH
• DELETE
• path parameters
• query parameters
• headers
• JSON request body
• JSON response body

GraphQL

• query
• mutation
• endpoint URL
• request headers
• operation template
• variables mapping
• извлечение результата из data

GraphQL в MCP публикуется как фиксированная операция с предсказуемой структурой ответа.

gRPC

• только unary RPC;
• .proto и descriptor set;
• JSON-oriented schema model поверх protobuf;
• без streaming.

8. Работа с файлами и автогенерация черновика

Поддерживаемые источники:

• пример входного JSON;
• пример выходного JSON;
• .proto;
• descriptor set.

Ожидаемый сценарий:

1. оператор загружает артефакты;
2. система строит черновую схему и mapping;
3. оператор вручную корректирует результат;
4. готовую конфигурацию можно экспортировать в YAML.

9. Внутренняя модель данных

Базовые сущности:

• Workspace
• Operation
• OperationVersion
• Agent
• AgentVersion
• AgentOperationBinding
• AuthProfile
• PlatformApiKey
• InvocationLog
• UsageRollup

10. MCP publishing model

Публикация tools строится так:

1. Operation проходит versioning и publish.
2. Agent собирает curated набор published operations.
3. MCP server читает published view конкретного agent.
4. tools/list и tools/call работают в контексте workspace + agent.

11. Observability

На каждый вызов tool сохраняются:

• workspace_id
• agent_id
• operation_id
• request_id
• timestamp
• status
• duration_ms
• error_kind
• request_preview
• response_preview

Сверху строятся:

• logs page;
• usage page;
• периодические rollups;
• latency and error aggregates.

12. Модель маппинга

Платформе нужен отдельный слой маппинга:

• сопоставление поле-в-поле по JSONPath;
• константы;
• значения по умолчанию;
• извлечение вложенных полей из ответа.