crank/docs/module-decomposition.md

Декомпозиция модулей

1. Цель документа

Этот документ фиксирует детальную структуру проекта под целевую модель workspace -> agent -> operations.

Основной принцип: каждый crate отвечает за один слой системы. Внутри crate модули маленькие, тематические и с минимальным количеством публичных сущностей.

2. Общие архитектурные правила

• core содержит только базовую доменную модель, идентификаторы, типы ошибок и общие контракты.
• registry отвечает только за хранение и загрузку workspace-scoped конфигурации.
• runtime исполняет операции, но не знает о способе их хранения.
• адаптеры знают только свой протокол и общий контракт runtime.
• admin-api оркестрирует use case для UI, но не содержит протокольной логики.
• mcp-server публикует agent-scoped tools и вызывает runtime.
• ui работает только через HTTP API.

3. Workspace-структура

crank/
  apps/
    admin-api/
    mcp-server/
    ui/
  crates/
    crank-core/
    crank-registry/
    crank-runtime/
    crank-adapter-rest/
    crank-adapter-graphql/
    crank-adapter-grpc/
    crank-mapping/
    crank-schema/
    crank-proto/

Поверх существующих crates должны появиться новые логические поддомены:

• workspace/access domain;
• secret management domain;
• agent publishing domain;
• observability domain.

4. Детальная декомпозиция по crate

4.1. crank-core

Назначение:

• базовые доменные типы;
• идентификаторы;
• метаданные workspace, operation и agent;
• общие контракты и ошибки.

Внутренние модули:

• ids
• protocol
• workspace
• operation
• agent
• auth
• secret
• observability
• errors

4.2. crank-schema

Назначение:

• внутренняя модель схем;
• нормализация входа и выхода;
• представление полей для UI и runtime.

4.3. crank-mapping

Назначение:

• mapping DSL;
• JSONPath parsing;
• input/output mapping;
• draft inference из samples.

4.4. crank-proto

Назначение:

• работа с .proto и descriptor set;
• извлечение services, methods и message schemas;
• преобразование protobuf metadata во внутренние типы.

4.5. crank-registry

Назначение:

• хранение workspace-scoped operations и version snapshots;
• хранение workspace-scoped secrets и secret versions;
• хранение agents и agent versions;
• auth profiles;
• platform API keys;
• logs и usage aggregates;
• metadata по sample artifacts и descriptors.

4.6. crank-runtime

Назначение:

• исполнение published operation;
• резолв auth_profile_ref -> secret -> request auth;
• запись invocation events;
• возврат нормализованного результата.

4.7. Protocol adapters

• crank-adapter-rest
• crank-adapter-graphql
• crank-adapter-grpc

Каждый adapter знает только свой протокол.

4.8. apps/admin-api

Должен содержать сервисные группы:

• workspaces
• secrets
• memberships
• operations
• auth_profiles
• agents
• platform_api_keys
• logs
• usage

4.9. apps/mcp-server

Назначение:

• публикация published agent bindings как MCP tools;
• transport handling;
• JSON-RPC lifecycle;
• вызов runtime.

Антипаттерн:

не превращать mcp-server во второй admin-api.