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

## 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-структура

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