# Архитектура

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

```text
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_*` методы.

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

```text
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.