github-ops
76 lines
3.1 KiB
Markdown
76 lines
3.1 KiB
Markdown
# Архитектура
|
||
|
||
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.
|