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`

Изолирует:

- операции;
- secrets;
- 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`
- `UserSession`
- `Membership`
- `Invitation`
- `PlatformApiKey`

### `Upstream secrets`

Отдельный слой для доступа к внешним системам:

- `Secret`
- `SecretVersion`
- `AuthProfile`

Принцип:

- секреты принадлежат workspace;
- plaintext не хранится в открытом виде;
- `AuthProfile` описывает способ применения секрета к upstream request;
- runtime резолвит `auth_profile_ref` в реальный header/query/basic auth только в момент вызова.

### `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. Границы целевого продукта

### Входит

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

### Отложено

- GraphQL `subscription`.
- gRPC client-streaming и bidirectional streaming.
- raw infinite stream passthrough.
- полный стек WS-* расширений.
- Оркестрация workflow.
- Биллинг.
- Full RBAC policy engine.
- Traffic splitting и deployment orchestration.

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

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

1. Выбирает workspace.
2. Создает или редактирует operation.
3. При необходимости выбирает или создает upstream secret / auth profile.
4. Выполняет test run.
5. Публикует operation version.
6. Привязывает 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;
- bounded server-streaming через `window`, `session` и `async_job` execution modes;
- `.proto` и `descriptor set`;
- JSON-oriented schema model поверх protobuf;
- без client-streaming и bidi.

### WebSocket

- upstream-only adapter;
- bounded `window`, `session` и `async_job`;
- subscribe/unsubscribe messages;
- heartbeat и reconnect policy;
- не используется как downstream MCP transport.

### SOAP

- WSDL-driven request-response integration;
- service/port/operation selection;
- SOAP envelope и fault normalization;
- request-response first;
- long-running workflows через `async_job`, если upstream это поддерживает.

### Streaming

Платформа поддерживает controlled streaming model:

- downstream transport: `Streamable HTTP` с optional SSE;
- upstream streaming: REST SSE, gRPC server-streaming и WebSocket;
- execution modes: `unary`, `window`, `session`, `async_job`;
- никакого raw infinite stream passthrough в MCP client.

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

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

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

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

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

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

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

- `Workspace`
- `Secret`
- `SecretVersion`
- `Operation`
- `OperationVersion`
- `Agent`
- `AgentVersion`
- `AgentOperationBinding`
- `StreamSession`
- `AsyncJobHandle`
- `AuthProfile`
- `PlatformApiKey`
- `UserSession`
- `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`;
- константы;
- значения по умолчанию;
- извлечение вложенных полей из ответа.