chore: rebrand project to crank
This commit is contained in:
a.tolmachev
@@ -2,7 +2,7 @@
|
||||
|
||||
## 1. Цель документа
|
||||
|
||||
Этот документ фиксирует детальную структуру проекта до начала активной разработки. Его задача - заранее ограничить ответственность каждого компонента, избежать разрастания `mcpaas-core`, не допустить появления "универсальных" структур на все случаи жизни и сохранить понятные границы между доменной логикой, runtime, адаптерами, API и UI.
|
||||
Этот документ фиксирует детальную структуру проекта до начала активной разработки. Его задача - заранее ограничить ответственность каждого компонента, избежать разрастания `crank-core`, не допустить появления "универсальных" структур на все случаи жизни и сохранить понятные границы между доменной логикой, runtime, адаптерами, API и UI.
|
||||
|
||||
Основной принцип: каждый crate отвечает за один слой системы. Внутри crate модули должны быть маленькими, тематическими и с минимальным количеством публичных сущностей.
|
||||
|
||||
@@ -20,7 +20,7 @@
|
||||
|
||||
### 2.2. Что запрещено
|
||||
|
||||
- помещать SQL, HTTP-клиенты или gRPC-клиенты в `mcpaas-core`;
|
||||
- помещать SQL, HTTP-клиенты или gRPC-клиенты в `crank-core`;
|
||||
- хранить в `core` "общие утилиты", не относящиеся к доменной модели;
|
||||
- делать `runtime`, который напрямую читает БД;
|
||||
- писать mapping-логику внутри REST, GraphQL или gRPC адаптеров;
|
||||
@@ -41,28 +41,28 @@
|
||||
Рекомендуемая структура:
|
||||
|
||||
```text
|
||||
mcpaas/
|
||||
crank/
|
||||
apps/
|
||||
admin-api/
|
||||
mcp-server/
|
||||
ui/
|
||||
crates/
|
||||
mcpaas-core/
|
||||
mcpaas-registry/
|
||||
mcpaas-runtime/
|
||||
mcpaas-adapter-rest/
|
||||
mcpaas-adapter-graphql/
|
||||
mcpaas-adapter-grpc/
|
||||
mcpaas-mapping/
|
||||
mcpaas-schema/
|
||||
mcpaas-proto/
|
||||
crank-core/
|
||||
crank-registry/
|
||||
crank-runtime/
|
||||
crank-adapter-rest/
|
||||
crank-adapter-graphql/
|
||||
crank-adapter-grpc/
|
||||
crank-mapping/
|
||||
crank-schema/
|
||||
crank-proto/
|
||||
```
|
||||
|
||||
Дополнительные crates `mcpaas-mapping`, `mcpaas-schema` и `mcpaas-proto` нужны затем, чтобы не перегружать `mcpaas-core`.
|
||||
Дополнительные crates `crank-mapping`, `crank-schema` и `crank-proto` нужны затем, чтобы не перегружать `crank-core`.
|
||||
|
||||
## 4. Детальная декомпозиция по crate
|
||||
|
||||
### 4.1. `mcpaas-core`
|
||||
### 4.1. `crank-core`
|
||||
|
||||
Назначение:
|
||||
|
||||
@@ -74,7 +74,7 @@ mcpaas/
|
||||
Что должно лежать в crate:
|
||||
|
||||
```text
|
||||
mcpaas-core/
|
||||
crank-core/
|
||||
src/
|
||||
lib.rs
|
||||
ids.rs
|
||||
@@ -119,9 +119,9 @@ mcpaas-core/
|
||||
|
||||
Причина:
|
||||
|
||||
`mcpaas-core` должен быть максимально стабильным и независимым. Если положить туда все подряд, он станет точкой связности всей системы.
|
||||
`crank-core` должен быть максимально стабильным и независимым. Если положить туда все подряд, он станет точкой связности всей системы.
|
||||
|
||||
### 4.2. `mcpaas-schema`
|
||||
### 4.2. `crank-schema`
|
||||
|
||||
Назначение:
|
||||
|
||||
@@ -133,7 +133,7 @@ mcpaas-core/
|
||||
Структура:
|
||||
|
||||
```text
|
||||
mcpaas-schema/
|
||||
crank-schema/
|
||||
src/
|
||||
lib.rs
|
||||
schema/
|
||||
@@ -173,7 +173,7 @@ mcpaas-schema/
|
||||
|
||||
Схемы будут использоваться почти везде, но это не повод тащить их в `core`. Иначе `core` станет тяжелым и начнет менять версию при каждом изменении схемной логики.
|
||||
|
||||
### 4.3. `mcpaas-mapping`
|
||||
### 4.3. `crank-mapping`
|
||||
|
||||
Назначение:
|
||||
|
||||
@@ -186,7 +186,7 @@ mcpaas-schema/
|
||||
Структура:
|
||||
|
||||
```text
|
||||
mcpaas-mapping/
|
||||
crank-mapping/
|
||||
src/
|
||||
lib.rs
|
||||
model/
|
||||
@@ -229,7 +229,7 @@ mcpaas-mapping/
|
||||
|
||||
не помещать mapping-правила в строковые поля, которые потом интерпретируются каждым адаптером по-своему. Mapping должен быть единым движком.
|
||||
|
||||
### 4.4. `mcpaas-proto`
|
||||
### 4.4. `crank-proto`
|
||||
|
||||
Назначение:
|
||||
|
||||
@@ -240,7 +240,7 @@ mcpaas-mapping/
|
||||
Структура:
|
||||
|
||||
```text
|
||||
mcpaas-proto/
|
||||
crank-proto/
|
||||
src/
|
||||
lib.rs
|
||||
descriptor/
|
||||
@@ -272,14 +272,14 @@ mcpaas-proto/
|
||||
- `descriptor/registry.rs` - индексирование описаний для поиска services/methods.
|
||||
- `reflect/client.rs` - клиент server reflection, если будет добавлен.
|
||||
- `model/*` - protobuf-ориентированная промежуточная модель.
|
||||
- `convert/to_schema.rs` - перевод protobuf message в `mcpaas-schema`.
|
||||
- `convert/to_schema.rs` - перевод protobuf message в `crank-schema`.
|
||||
- `convert/to_json.rs` и `from_json.rs` - преобразование runtime payload.
|
||||
|
||||
Почему отдельный crate:
|
||||
|
||||
protobuf-логика объемная и быстро начнет загрязнять gRPC adapter, если не отделить ее сразу.
|
||||
|
||||
### 4.5. `mcpaas-registry`
|
||||
### 4.5. `crank-registry`
|
||||
|
||||
Назначение:
|
||||
|
||||
@@ -290,7 +290,7 @@ protobuf-логика объемная и быстро начнет загряз
|
||||
Структура:
|
||||
|
||||
```text
|
||||
mcpaas-registry/
|
||||
crank-registry/
|
||||
src/
|
||||
lib.rs
|
||||
model/
|
||||
@@ -332,7 +332,7 @@ mcpaas-registry/
|
||||
|
||||
`registry` не выполняет операции и не знает о `reqwest`/`tonic`. Он только хранит и отдает согласованные представления.
|
||||
|
||||
### 4.6. `mcpaas-runtime`
|
||||
### 4.6. `crank-runtime`
|
||||
|
||||
Назначение:
|
||||
|
||||
@@ -343,7 +343,7 @@ mcpaas-registry/
|
||||
Структура:
|
||||
|
||||
```text
|
||||
mcpaas-runtime/
|
||||
crank-runtime/
|
||||
src/
|
||||
lib.rs
|
||||
executor/
|
||||
@@ -380,7 +380,7 @@ mcpaas-runtime/
|
||||
|
||||
`runtime` не должен знать, где хранится операция. Он получает уже готовую `runtime_operation`.
|
||||
|
||||
### 4.7. `mcpaas-adapter-rest`
|
||||
### 4.7. `crank-adapter-rest`
|
||||
|
||||
Назначение:
|
||||
|
||||
@@ -389,7 +389,7 @@ mcpaas-runtime/
|
||||
Структура:
|
||||
|
||||
```text
|
||||
mcpaas-adapter-rest/
|
||||
crank-adapter-rest/
|
||||
src/
|
||||
lib.rs
|
||||
client.rs
|
||||
@@ -411,7 +411,7 @@ mcpaas-adapter-rest/
|
||||
|
||||
REST adapter не валидирует MCP input и не знает о registry. Он получает уже подготовленный request contract.
|
||||
|
||||
### 4.8. `mcpaas-adapter-graphql`
|
||||
### 4.8. `crank-adapter-graphql`
|
||||
|
||||
Назначение:
|
||||
|
||||
@@ -420,7 +420,7 @@ REST adapter не валидирует MCP input и не знает о registry.
|
||||
Структура:
|
||||
|
||||
```text
|
||||
mcpaas-adapter-graphql/
|
||||
crank-adapter-graphql/
|
||||
src/
|
||||
lib.rs
|
||||
client.rs
|
||||
@@ -443,7 +443,7 @@ GraphQL adapter не занимается introspection по умолчанию
|
||||
|
||||
один GraphQL tool соответствует одному заранее определенному `query` или `mutation`. Адаптер не должен принимать от LLM произвольный GraphQL-документ, потому что в MCP-модели операция должна оставаться узкой, предсказуемой и валидируемой по фиксированной схеме.
|
||||
|
||||
### 4.9. `mcpaas-adapter-grpc`
|
||||
### 4.9. `crank-adapter-grpc`
|
||||
|
||||
Назначение:
|
||||
|
||||
@@ -452,7 +452,7 @@ GraphQL adapter не занимается introspection по умолчанию
|
||||
Структура:
|
||||
|
||||
```text
|
||||
mcpaas-adapter-grpc/
|
||||
crank-adapter-grpc/
|
||||
src/
|
||||
lib.rs
|
||||
channel.rs
|
||||
@@ -470,7 +470,7 @@ mcpaas-adapter-grpc/
|
||||
|
||||
Правило:
|
||||
|
||||
gRPC adapter не должен сам парсить `.proto`. Этим занимается `mcpaas-proto`. Иначе в адаптере смешаются discovery и execution.
|
||||
gRPC adapter не должен сам парсить `.proto`. Этим занимается `crank-proto`. Иначе в адаптере смешаются discovery и execution.
|
||||
|
||||
Дополнительное ограничение:
|
||||
|
||||
@@ -609,22 +609,22 @@ UI должен декомпозироваться по пользователь
|
||||
Целевой граф зависимостей:
|
||||
|
||||
```text
|
||||
mcpaas-core
|
||||
mcpaas-schema -> mcpaas-core
|
||||
mcpaas-mapping -> mcpaas-core
|
||||
mcpaas-proto -> mcpaas-core, mcpaas-schema
|
||||
mcpaas-registry -> mcpaas-core, mcpaas-schema, mcpaas-mapping
|
||||
mcpaas-adapter-rest -> mcpaas-core
|
||||
mcpaas-adapter-graphql -> mcpaas-core
|
||||
mcpaas-adapter-grpc -> mcpaas-core, mcpaas-proto
|
||||
mcpaas-runtime -> mcpaas-core, mcpaas-schema, mcpaas-mapping, adapters
|
||||
admin-api -> mcpaas-core, mcpaas-schema, mcpaas-mapping, mcpaas-proto, mcpaas-registry, mcpaas-runtime
|
||||
mcp-server -> mcpaas-core, mcpaas-registry, mcpaas-runtime
|
||||
crank-core
|
||||
crank-schema -> crank-core
|
||||
crank-mapping -> crank-core
|
||||
crank-proto -> crank-core, crank-schema
|
||||
crank-registry -> crank-core, crank-schema, crank-mapping
|
||||
crank-adapter-rest -> crank-core
|
||||
crank-adapter-graphql -> crank-core
|
||||
crank-adapter-grpc -> crank-core, crank-proto
|
||||
crank-runtime -> crank-core, crank-schema, crank-mapping, adapters
|
||||
admin-api -> crank-core, crank-schema, crank-mapping, crank-proto, crank-registry, crank-runtime
|
||||
mcp-server -> crank-core, crank-registry, crank-runtime
|
||||
```
|
||||
|
||||
Критические ограничения:
|
||||
|
||||
- `mcpaas-core` ни от кого не зависит;
|
||||
- `crank-core` ни от кого не зависит;
|
||||
- адаптеры не зависят от `registry`;
|
||||
- `runtime` не зависит от `admin-api` и `mcp-server`;
|
||||
- `registry` не зависит от адаптеров;
|
||||
@@ -675,17 +675,17 @@ mcp-server -> mcpaas-core, mcpaas-registry, mcpaas-runtime
|
||||
|
||||
Рекомендуемый порядок разработки:
|
||||
|
||||
1. `mcpaas-core`
|
||||
2. `mcpaas-schema`
|
||||
3. `mcpaas-mapping`
|
||||
4. `mcpaas-registry`
|
||||
5. `mcpaas-adapter-rest`
|
||||
6. `mcpaas-runtime`
|
||||
1. `crank-core`
|
||||
2. `crank-schema`
|
||||
3. `crank-mapping`
|
||||
4. `crank-registry`
|
||||
5. `crank-adapter-rest`
|
||||
6. `crank-runtime`
|
||||
7. `admin-api`
|
||||
8. `ui`
|
||||
9. `mcpaas-proto`
|
||||
10. `mcpaas-adapter-grpc`
|
||||
11. `mcpaas-adapter-graphql`
|
||||
9. `crank-proto`
|
||||
10. `crank-adapter-grpc`
|
||||
11. `crank-adapter-graphql`
|
||||
12. `mcp-server`
|
||||
|
||||
Причина такого порядка:
|
||||
@@ -699,7 +699,7 @@ mcp-server -> mcpaas-core, mcpaas-registry, mcpaas-runtime
|
||||
|
||||
Если придерживаться этой декомпозиции, то:
|
||||
|
||||
- `mcpaas-core` останется маленьким и стабильным;
|
||||
- `crank-core` останется маленьким и стабильным;
|
||||
- schema и mapping не смешаются с transport-логикой;
|
||||
- protobuf discovery не загрязнит gRPC runtime;
|
||||
- `admin-api` и `mcp-server` останутся тонкими входными слоями;
|
||||
|
||||
Reference in New Issue
Block a user