chore: publish clean community baseline

2026-06-17 06:15:46 +00:00
commit ba29ac7b94
320 changed files with 73936 additions and 0 deletions
@@ -0,0 +1,53 @@
+# Архитектура
+
+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.
+
+## Хранилище
+
+PostgreSQL хранит:
+
+- users и sessions;
+- workspaces;
+- operations и versions;
+- agents и bindings;
+- secrets и auth profiles;
+- logs и usage.
+
+Файловое хранилище используется для samples и YAML import payloads.