docs: redesign architecture around workspaces and agents
This commit is contained in:
a.tolmachev
+70
-306
@@ -2,14 +2,11 @@
|
||||
|
||||
## 1. Назначение документа
|
||||
|
||||
Этот документ собирает диаграммы, которые фиксируют проект до начала разработки:
|
||||
Этот документ собирает диаграммы целевой модели проекта:
|
||||
|
||||
- компонентную структуру;
|
||||
- связи между доменными сущностями;
|
||||
- хранение данных в БД;
|
||||
- основные runtime и admin-потоки.
|
||||
|
||||
Диаграммы даны в формате `Mermaid`, чтобы их можно было хранить прямо в репозитории и рендерить в Markdown-compatible tooling.
|
||||
- хранение данных в БД.
|
||||
|
||||
## 2. Компонентная диаграмма
|
||||
|
||||
@@ -29,6 +26,7 @@ flowchart LR
|
||||
GRPC[adapter-grpc]
|
||||
DB[(PostgreSQL)]
|
||||
STORE[(Artifact Storage)]
|
||||
OBS[(Usage and Logs)]
|
||||
|
||||
UI --> ADMIN
|
||||
MCP --> REG
|
||||
@@ -36,352 +34,118 @@ flowchart LR
|
||||
ADMIN --> REG
|
||||
ADMIN --> RUN
|
||||
ADMIN --> PROTO
|
||||
|
||||
REG --> DB
|
||||
REG --> CORE
|
||||
REG --> SCHEMA
|
||||
REG --> MAP
|
||||
|
||||
RUN --> CORE
|
||||
RUN --> SCHEMA
|
||||
RUN --> MAP
|
||||
RUN --> REST
|
||||
RUN --> GQL
|
||||
RUN --> GRPC
|
||||
|
||||
GRPC --> PROTO
|
||||
PROTO --> STORE
|
||||
ADMIN --> STORE
|
||||
REG --> OBS
|
||||
ADMIN --> OBS
|
||||
```
|
||||
|
||||
## 3. Диаграмма зависимостей crates
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
CORE[crank-core]
|
||||
SCHEMA[crank-schema]
|
||||
MAP[crank-mapping]
|
||||
PROTO[crank-proto]
|
||||
REG[crank-registry]
|
||||
RUN[crank-runtime]
|
||||
REST[crank-adapter-rest]
|
||||
GQL[crank-adapter-graphql]
|
||||
GRPC[crank-adapter-grpc]
|
||||
ADMIN[apps/admin-api]
|
||||
MCP[apps/mcp-server]
|
||||
|
||||
SCHEMA --> CORE
|
||||
MAP --> CORE
|
||||
PROTO --> CORE
|
||||
PROTO --> SCHEMA
|
||||
REG --> CORE
|
||||
REG --> SCHEMA
|
||||
REG --> MAP
|
||||
REST --> CORE
|
||||
GQL --> CORE
|
||||
GRPC --> CORE
|
||||
GRPC --> PROTO
|
||||
RUN --> CORE
|
||||
RUN --> SCHEMA
|
||||
RUN --> MAP
|
||||
RUN --> REST
|
||||
RUN --> GQL
|
||||
RUN --> GRPC
|
||||
ADMIN --> CORE
|
||||
ADMIN --> SCHEMA
|
||||
ADMIN --> MAP
|
||||
ADMIN --> PROTO
|
||||
ADMIN --> REG
|
||||
ADMIN --> RUN
|
||||
MCP --> CORE
|
||||
MCP --> REG
|
||||
MCP --> RUN
|
||||
```
|
||||
|
||||
## 4. Структурная диаграмма доменной модели
|
||||
## 3. Структурная диаграмма доменной модели
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class Workspace {
|
||||
+id
|
||||
+slug
|
||||
+display_name
|
||||
}
|
||||
|
||||
class Operation {
|
||||
+id
|
||||
+workspace_id
|
||||
+name
|
||||
+display_name
|
||||
+protocol
|
||||
+status
|
||||
+version
|
||||
+target
|
||||
+input_schema
|
||||
+output_schema
|
||||
+input_mapping
|
||||
+output_mapping
|
||||
+execution_config
|
||||
+tool_description
|
||||
+samples
|
||||
+generated_draft
|
||||
+config_export
|
||||
}
|
||||
|
||||
class RestTarget {
|
||||
+base_url
|
||||
+method
|
||||
+path_template
|
||||
+static_headers
|
||||
}
|
||||
|
||||
class GraphqlTarget {
|
||||
+endpoint
|
||||
+operation_type
|
||||
+operation_name
|
||||
+query_template
|
||||
+response_path
|
||||
}
|
||||
|
||||
class GrpcTarget {
|
||||
+server_addr
|
||||
+package
|
||||
+service
|
||||
+method
|
||||
+descriptor_ref
|
||||
+descriptor_set_b64
|
||||
}
|
||||
|
||||
class Schema {
|
||||
+type
|
||||
+description
|
||||
+fields
|
||||
}
|
||||
|
||||
class MappingSet {
|
||||
+rules[]
|
||||
}
|
||||
|
||||
class MappingRule {
|
||||
+source
|
||||
+target
|
||||
+required
|
||||
+default_value
|
||||
+transform
|
||||
+condition
|
||||
}
|
||||
|
||||
class ExecutionConfig {
|
||||
+timeout_ms
|
||||
+retry_policy
|
||||
+auth_profile_ref
|
||||
+headers
|
||||
+protocol_options
|
||||
}
|
||||
|
||||
class AuthProfile {
|
||||
class Agent {
|
||||
+id
|
||||
+name
|
||||
+kind
|
||||
+config
|
||||
}
|
||||
|
||||
class ToolDescription {
|
||||
+title
|
||||
+description
|
||||
+tags
|
||||
+examples
|
||||
}
|
||||
|
||||
class Samples {
|
||||
+input_json_sample_ref
|
||||
+output_json_sample_ref
|
||||
+proto_file_ref
|
||||
+descriptor_ref
|
||||
}
|
||||
|
||||
class GeneratedDraft {
|
||||
+workspace_id
|
||||
+slug
|
||||
+display_name
|
||||
+status
|
||||
+source_types
|
||||
+generated_at
|
||||
+warnings
|
||||
}
|
||||
|
||||
Operation --> RestTarget : target
|
||||
Operation --> GraphqlTarget : target
|
||||
Operation --> GrpcTarget : target
|
||||
Operation --> Schema : input_schema
|
||||
Operation --> Schema : output_schema
|
||||
Operation --> MappingSet : input_mapping
|
||||
Operation --> MappingSet : output_mapping
|
||||
Operation --> ExecutionConfig : execution_config
|
||||
Operation --> ToolDescription : tool_description
|
||||
Operation --> Samples : samples
|
||||
Operation --> GeneratedDraft : generated_draft
|
||||
ExecutionConfig --> AuthProfile : auth_profile_ref
|
||||
MappingSet --> MappingRule : contains
|
||||
class AgentBinding {
|
||||
+operation_id
|
||||
+operation_version
|
||||
+tool_name
|
||||
+enabled
|
||||
}
|
||||
|
||||
class PlatformApiKey {
|
||||
+id
|
||||
+workspace_id
|
||||
+name
|
||||
+prefix
|
||||
+scopes
|
||||
+status
|
||||
}
|
||||
|
||||
class InvocationLog {
|
||||
+workspace_id
|
||||
+agent_id
|
||||
+operation_id
|
||||
+status
|
||||
+duration_ms
|
||||
}
|
||||
|
||||
Workspace --> Operation : owns
|
||||
Workspace --> Agent : owns
|
||||
Workspace --> PlatformApiKey : owns
|
||||
Agent --> AgentBinding : contains
|
||||
AgentBinding --> Operation : references
|
||||
InvocationLog --> Workspace : belongs_to
|
||||
InvocationLog --> Agent : belongs_to
|
||||
InvocationLog --> Operation : belongs_to
|
||||
```
|
||||
|
||||
## 5. ER-диаграмма БД
|
||||
## 4. ER-диаграмма БД
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
WORKSPACES ||--o{ OPERATIONS : owns
|
||||
WORKSPACES ||--o{ AGENTS : owns
|
||||
WORKSPACES ||--o{ AUTH_PROFILES : owns
|
||||
WORKSPACES ||--o{ PLATFORM_API_KEYS : owns
|
||||
WORKSPACES ||--o{ INVOCATION_LOGS : owns
|
||||
OPERATIONS ||--o{ OPERATION_VERSIONS : has
|
||||
OPERATIONS ||--o| PUBLISHED_OPERATIONS : publishes
|
||||
OPERATIONS ||--o{ OPERATION_SAMPLES : owns
|
||||
OPERATIONS ||--o{ DESCRIPTORS : may_use
|
||||
OPERATIONS ||--o{ YAML_IMPORT_JOBS : may_create
|
||||
AUTH_PROFILES ||--o{ OPERATION_VERSIONS : referenced_by
|
||||
AGENTS ||--o{ AGENT_VERSIONS : has
|
||||
AGENTS ||--o| PUBLISHED_AGENTS : publishes
|
||||
AGENT_VERSIONS ||--o{ AGENT_OPERATION_BINDINGS : contains
|
||||
OPERATIONS ||--o{ AGENT_OPERATION_BINDINGS : exposed_by
|
||||
|
||||
WORKSPACES {
|
||||
text id PK
|
||||
text slug
|
||||
text display_name
|
||||
}
|
||||
OPERATIONS {
|
||||
text id PK
|
||||
text workspace_id FK
|
||||
text name
|
||||
text display_name
|
||||
text protocol
|
||||
text status
|
||||
int current_draft_version
|
||||
int latest_published_version
|
||||
timestamptz created_at
|
||||
timestamptz updated_at
|
||||
timestamptz published_at
|
||||
}
|
||||
|
||||
OPERATION_VERSIONS {
|
||||
text operation_id FK
|
||||
int version
|
||||
AGENTS {
|
||||
text id PK
|
||||
text workspace_id FK
|
||||
text slug
|
||||
text display_name
|
||||
text status
|
||||
jsonb target_json
|
||||
jsonb input_schema_json
|
||||
jsonb output_schema_json
|
||||
jsonb input_mapping_json
|
||||
jsonb output_mapping_json
|
||||
jsonb execution_config_json
|
||||
jsonb tool_description_json
|
||||
jsonb samples_json
|
||||
jsonb generated_draft_json
|
||||
jsonb config_export_json
|
||||
timestamptz created_at
|
||||
}
|
||||
|
||||
PUBLISHED_OPERATIONS {
|
||||
text operation_id PK
|
||||
int version
|
||||
timestamptz published_at
|
||||
text published_by
|
||||
}
|
||||
|
||||
OPERATION_SAMPLES {
|
||||
text id PK
|
||||
text operation_id FK
|
||||
int version
|
||||
text sample_kind
|
||||
text storage_ref
|
||||
text content_type
|
||||
text file_name
|
||||
timestamptz created_at
|
||||
}
|
||||
|
||||
DESCRIPTORS {
|
||||
text id PK
|
||||
text operation_id FK
|
||||
int version
|
||||
text descriptor_kind
|
||||
text storage_ref
|
||||
jsonb package_index_json
|
||||
timestamptz created_at
|
||||
}
|
||||
|
||||
YAML_IMPORT_JOBS {
|
||||
text id PK
|
||||
text source_sample_id
|
||||
text status
|
||||
text format_version
|
||||
text mode
|
||||
text result_operation_id
|
||||
int result_version
|
||||
text error_text
|
||||
timestamptz created_at
|
||||
timestamptz finished_at
|
||||
}
|
||||
|
||||
AUTH_PROFILES {
|
||||
text id PK
|
||||
text name
|
||||
text kind
|
||||
jsonb config_json
|
||||
timestamptz created_at
|
||||
timestamptz updated_at
|
||||
}
|
||||
```
|
||||
|
||||
## 6. Sequence: создание и публикация operation
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI
|
||||
participant API as admin-api
|
||||
participant REG as registry
|
||||
participant RUN as runtime
|
||||
participant MCP as mcp-server
|
||||
|
||||
UI->>API: POST /operations
|
||||
API->>REG: create operation v1
|
||||
REG-->>API: created
|
||||
API-->>UI: operation_id, version
|
||||
|
||||
UI->>API: upload samples / descriptors
|
||||
API-->>UI: artifact refs
|
||||
|
||||
UI->>API: POST /drafts/generate
|
||||
API->>REG: save generated draft metadata
|
||||
API-->>UI: generated draft
|
||||
|
||||
UI->>API: POST /test-runs
|
||||
API->>RUN: execute draft version
|
||||
RUN-->>API: request_preview + response_preview
|
||||
API-->>UI: test result
|
||||
|
||||
UI->>API: POST /publish
|
||||
API->>REG: mark version as published
|
||||
REG-->>API: published
|
||||
API-->>MCP: reload signal
|
||||
API-->>UI: published_version
|
||||
```
|
||||
|
||||
## 7. Sequence: MCP tool execution
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Client as MCP Client
|
||||
participant MCP as mcp-server
|
||||
participant REG as registry/cache
|
||||
participant RUN as runtime
|
||||
participant ADP as protocol adapter
|
||||
|
||||
Client->>MCP: call tool(name, input)
|
||||
MCP->>REG: resolve published runtime view
|
||||
REG-->>MCP: runtime operation
|
||||
MCP->>RUN: execute(operation, input)
|
||||
RUN->>RUN: validate input schema
|
||||
RUN->>RUN: apply input mapping
|
||||
RUN->>ADP: execute prepared request
|
||||
ADP-->>RUN: normalized response
|
||||
RUN->>RUN: apply output mapping
|
||||
RUN-->>MCP: output
|
||||
MCP-->>Client: tool result
|
||||
```
|
||||
|
||||
## 8. Sequence: YAML import
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI
|
||||
participant API as admin-api
|
||||
participant REG as registry
|
||||
|
||||
UI->>API: POST /operations/import (YAML)
|
||||
API->>API: parse YAML
|
||||
API->>API: validate schema, target, mapping
|
||||
API->>REG: create or upsert new version
|
||||
REG-->>API: operation_id, version
|
||||
API-->>UI: import result
|
||||
```
|
||||
|
||||
## 9. Что важно помнить
|
||||
|
||||
- Диаграммы фиксируют целевую архитектуру, а не точную реализацию каждого файла.
|
||||
- Если меняется модель данных или поток исполнения, сначала нужно обновлять документы, потом код.
|
||||
- Для старта разработки этого набора достаточно: компоненты, сущности, БД и ключевые sequence flows уже описаны.
|
||||
|
||||
Reference in New Issue
Block a user