# guzhujushi/trimum architecture

> Architecture diagram of the GitHub repository guzhujushi/trimum, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/guzhujushi/trimum
- Repository: https://github.com/guzhujushi/trimum

## Overview

trimum is a Python AI-process runtime: users submit work through the CLI or other documented interfaces, which is transformed into workflow actions, planned when needed, checked by security policy, and executed through a unified tool gateway. The graph retains documented memory, MCP, agent-runtime, audit, and event capabilities. Some of these implementations were not excerpted, so their documented presence is shown without speculative implementation-level connections.

Main entry points: [`src/trimum_core/workflow_engine.py`](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/workflow_engine.py) (Workflow engine), [`src/trimum_core/tool_gateway.py`](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/tool_gateway.py) (Tool gateway), [`src/trimum_core/cli/commands`](https://github.com/guzhujushi/trimum/tree/main/src/trimum_core/cli/commands) (CLI commands), [`src/trimum_core/workflow_runtime.py`](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/workflow_runtime.py) (Workflow runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI commands"]
  node_parser["CLI parser<br/>[parser.py]"]
  node_cli_utils["CLI helpers<br/>[_utils.py]"]
  node_api["Web API<br/>[api_server.py]"]
end

subgraph group_orchestration["Workflow orchestration"]
  node_transform["Request transform<br/>[transform_agent.py]"]
  node_workflow["Workflow engine<br/>[workflow_engine.py]"]
  node_workflow_runtime["Workflow runtime"]
  node_planner["Fallback planner<br/>[planner_agent.py]"]
  node_workflow_catalog["Workflow catalog"]
end

subgraph group_execution["Secure execution"]
  node_gateway["Tool gateway<br/>[tool_gateway.py]"]
  node_policy["Policy engine<br/>[policy_engine.py]"]
  node_dispatchers["Tool dispatchers"]
  node_sandbox["Sandbox execution<br/>[sandbox_exec.py]"]
  node_seccomp["Seccomp execution<br/>[seccomp_exec.py]"]
end

subgraph group_runtime["Runtime services"]
  node_event_bus["Event bus<br/>[event_bus.py]"]
  node_event_index["Event index<br/>[event_index.py]"]
  node_memory["Memory classifier"]
  node_audit[("Audit store<br/>[audit_store.py]")]
  node_models["Core models<br/>[models.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_ipc["JSON-RPC IPC<br/>[ipc_handler.py]"]
  node_logger["Structured logging<br/>[logger.py]"]
  node_paths["Runtime paths<br/>[paths.py]"]
end

subgraph group_ecosystem["Agent ecosystem"]
  node_mcp_registry["MCP registry<br/>[mcp_registry.py]"]
  node_mcp_client["MCP client<br/>[mcp_client.py]"]
  node_agents["Agent runtime<br/>[agent_runtime.py]"]
  node_agent_manager["Agent manager<br/>[agent_manager.py]"]
end

node_user(("User"))

node_user -->|"submits request"| node_cli
node_cli -->|"parses commands"| node_parser
node_parser -->|"uses helpers"| node_cli_utils
node_cli -->|"transforms request"| node_transform
node_transform -->|"routes labels"| node_workflow
node_workflow -->|"plans fallback"| node_planner
node_workflow -->|"runs workflow"| node_workflow_runtime
node_workflow -->|"emits events"| node_event_bus
node_workflow_runtime -->|"subscribes events"| node_event_bus
node_workflow -.->|"matches workflows"| node_workflow_catalog
node_workflow -->|"dispatches tools"| node_gateway
node_workflow -->|"uses task models"| node_models
node_event_bus -->|"indexes listeners"| node_event_index
node_gateway -->|"checks permissions"| node_policy
node_gateway -.->|"dispatches tools"| node_dispatchers
node_dispatchers -->|"executes commands"| node_sandbox
node_dispatchers -->|"uses seccomp"| node_seccomp
node_gateway -.->|"discovers MCP"| node_mcp_registry
node_mcp_registry -->|"manages clients"| node_mcp_client
node_agents -.->|"uses tool gateway"| node_gateway
node_agent_manager -.->|"manages agents"| node_agents
node_cli -.->|"manages memories"| node_memory
node_workflow_runtime -->|"records execution"| node_audit
node_ipc -->|"proxies requests"| node_api
node_config -.->|"selects paths"| node_paths
node_logger -->|"reads logging settings"| node_config

click node_cli "https://github.com/guzhujushi/trimum/tree/main/src/trimum_core/cli/commands"
click node_parser "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/cli/parser.py"
click node_cli_utils "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/cli/_utils.py"
click node_api "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/api_server.py"
click node_transform "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/transform_agent.py"
click node_workflow "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/workflow_engine.py"
click node_workflow_runtime "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/workflow_runtime.py"
click node_planner "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/planner_agent.py"
click node_workflow_catalog "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/workflow_catalog.py"
click node_event_bus "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/event_bus.py"
click node_event_index "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/event_index.py"
click node_gateway "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/tool_gateway.py"
click node_policy "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/policy_engine.py"
click node_dispatchers "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/tool_dispatchers.py"
click node_sandbox "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/sandbox_exec.py"
click node_seccomp "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/seccomp_exec.py"
click node_mcp_registry "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/mcp_registry.py"
click node_mcp_client "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/mcp_client.py"
click node_agents "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/agent_runtime.py"
click node_agent_manager "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/agent_manager.py"
click node_memory "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/memory_classifier.py"
click node_audit "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/audit_store.py"
click node_models "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/models.py"
click node_config "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/config.py"
click node_ipc "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/ipc_handler.py"
click node_logger "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/logger.py"
click node_paths "https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/paths.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_parser,node_cli_utils,node_api,node_user toneBlue
class node_transform,node_workflow,node_workflow_runtime,node_planner,node_workflow_catalog toneAmber
class node_gateway,node_policy,node_dispatchers,node_sandbox,node_seccomp toneMint
class node_event_bus,node_event_index,node_memory,node_audit,node_models,node_config,node_ipc,node_logger,node_paths toneRose
class node_mcp_registry,node_mcp_client,node_agents,node_agent_manager toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/guzhujushi/trimum/tree/main/src/trimum_core/cli/commands): `src/trimum_core/cli/commands`
- [CLI parser](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/cli/parser.py): `src/trimum_core/cli/parser.py`
- [CLI helpers](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/cli/_utils.py): `src/trimum_core/cli/_utils.py`
- [Web API](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/api_server.py): `src/trimum_core/api_server.py`

### Workflow orchestration

- [Request transform](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/transform_agent.py): `src/trimum_core/transform_agent.py`
- [Workflow engine](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/workflow_engine.py): `src/trimum_core/workflow_engine.py`
- [Workflow runtime](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/workflow_runtime.py): `src/trimum_core/workflow_runtime.py`
- [Fallback planner](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/planner_agent.py): `src/trimum_core/planner_agent.py`
- [Workflow catalog](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/workflow_catalog.py): `src/trimum_core/workflow_catalog.py`

### Secure execution

- [Tool gateway](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/tool_gateway.py): `src/trimum_core/tool_gateway.py`
- [Policy engine](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/policy_engine.py): `src/trimum_core/policy_engine.py`
- [Tool dispatchers](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/tool_dispatchers.py): `src/trimum_core/tool_dispatchers.py`
- [Sandbox execution](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/sandbox_exec.py): `src/trimum_core/sandbox_exec.py`
- [Seccomp execution](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/seccomp_exec.py): `src/trimum_core/seccomp_exec.py`

### Runtime services

- [Event bus](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/event_bus.py): `src/trimum_core/event_bus.py`
- [Event index](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/event_index.py): `src/trimum_core/event_index.py`
- [Memory classifier](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/memory_classifier.py): `src/trimum_core/memory_classifier.py`
- [Audit store](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/audit_store.py): `src/trimum_core/audit_store.py`
- [Core models](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/models.py): `src/trimum_core/models.py`
- [Configuration](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/config.py): `src/trimum_core/config.py`
- [JSON-RPC IPC](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/ipc_handler.py): `src/trimum_core/ipc_handler.py`
- [Structured logging](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/logger.py): `src/trimum_core/logger.py`
- [Runtime paths](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/paths.py): `src/trimum_core/paths.py`

### Agent ecosystem

- [MCP registry](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/mcp_registry.py): `src/trimum_core/mcp_registry.py`
- [MCP client](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/mcp_client.py): `src/trimum_core/mcp_client.py`
- [Agent runtime](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/agent_runtime.py): `src/trimum_core/agent_runtime.py`
- [Agent manager](https://github.com/guzhujushi/trimum/blob/main/src/trimum_core/agent_manager.py): `src/trimum_core/agent_manager.py`

### Other components

- **User**

## Connections

- User → CLI commands: submits request
- CLI commands → CLI parser: parses commands (evidence: `src/trimum_core/cli/parser.py`)
- CLI parser → CLI helpers: uses helpers (evidence: `src/trimum_core/cli/parser.py`)
- CLI commands → Request transform: transforms request (evidence: `src/trimum_core/cli/commands/workflow.py`)
- Request transform → Workflow engine: routes labels
- Workflow engine → Fallback planner: plans fallback
- Workflow engine → Workflow runtime: runs workflow (evidence: `src/trimum_core/workflow_runtime.py`)
- Workflow engine → Event bus: emits events (evidence: `src/trimum_core/workflow_engine.py`)
- Workflow runtime → Event bus: subscribes events (evidence: `src/trimum_core/workflow_runtime.py`)
- Workflow engine → Workflow catalog: matches workflows
- Workflow engine → Tool gateway: dispatches tools (evidence: `src/trimum_core/workflow_runtime.py`)
- Workflow engine → Core models: uses task models (evidence: `src/trimum_core/workflow_engine.py`)
- Event bus → Event index: indexes listeners (evidence: `src/trimum_core/event_bus.py`)
- Tool gateway → Policy engine: checks permissions
- Tool gateway → Tool dispatchers: dispatches tools
- Tool dispatchers → Sandbox execution: executes commands (evidence: `src/trimum_core/tool_dispatchers.py`)
- Tool dispatchers → Seccomp execution: uses seccomp (evidence: `src/trimum_core/tool_dispatchers.py`)
- Tool gateway → MCP registry: discovers MCP
- MCP registry → MCP client: manages clients (evidence: `src/trimum_core/mcp_registry.py`)
- Agent runtime → Tool gateway: uses tool gateway
- Agent manager → Agent runtime: manages agents
- CLI commands → Memory classifier: manages memories
- Workflow runtime → Audit store: records execution (evidence: `src/trimum_core/workflow_runtime.py`)
- JSON-RPC IPC → Web API: proxies requests (evidence: `src/trimum_core/ipc_handler.py`)
- Configuration → Runtime paths: selects paths
- Structured logging → Configuration: reads logging settings (evidence: `src/trimum_core/logger.py`)