# grim-sudo/automation architecture

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

- Interactive diagram: https://gitdiagram.com/grim-sudo/automation
- Repository: https://github.com/grim-sudo/automation

## Overview

Archon turns CLI, chatbot, or GUI requests into cross-platform automation, with separate routes for n8n workflows and Linux ISO builds. Its principal path is intent interpretation, command planning, workflow execution, then plugin or OS-adapter actions; AI model access supports planning and conversation. Other documented capabilities include project/DevOps/document generation, web automation, and file operations. The README documents these capabilities, but sampled source is partial, so the graph omits uncertain internal call wiring and represents only supported orchestration and integrations.

Main entry points: [`archon/core/engine.py`](https://github.com/grim-sudo/automation/blob/master/archon/core/engine.py) (Core engine), [`archon/workflow/engine.py`](https://github.com/grim-sudo/automation/blob/master/archon/workflow/engine.py) (Workflow engine), [`archon/core/plugin_manager.py`](https://github.com/grim-sudo/automation/blob/master/archon/core/plugin_manager.py) (Plugin manager), [`archon/ui/chatbot.py`](https://github.com/grim-sudo/automation/blob/master/archon/ui/chatbot.py) (Chatbot)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["Unified CLI<br/>[_cli.py]"]
  node_gui["GUI application<br/>[app.py]"]
  node_chatbot["Chatbot<br/>[chatbot.py]"]
end

subgraph group_orchestration["Intent and orchestration"]
  node_core["Core engine<br/>[engine.py]"]
  node_nlp["Semantic NLP<br/>[semantic_engine.py]"]
  node_parser["Command parser<br/>[command_parser.py]"]
  node_workflow["Workflow engine<br/>[engine.py]"]
  node_plugin_mgr["Plugin manager<br/>[plugin_manager.py]"]
end

subgraph group_automation["Automation capabilities"]
  node_capabilities["Capability registry<br/>[registry.py]"]
  node_native["File and document actions<br/>[filesystem.py]"]
  node_plugins["Automation plugins"]
  node_adapters["OS adapters<br/>[adapter_factory.py]"]
  node_security["Permission controls"]
end

subgraph group_specialized["Specialized workflows"]
  node_n8n["n8n workflow bridge"]
  node_triggers["Execution triggers<br/>[trigger_engine.py]"]
  node_distro["ISO build pipeline<br/>[build_pipeline.py]"]
end

subgraph group_ai["AI services"]
  node_planner["AI task planner<br/>[task_planner.py]"]
  node_models["Model manager<br/>[model_manager.py]"]
  node_context["Conversation context<br/>[context_manager.py]"]
end

node_user(("User"))
node_openrouter{{"OpenRouter API"}}
node_n8n_service{{"n8n service"}}
node_operating_system{{"Host operating system"}}
node_build_tools{{"Kernel and ISO tools"}}

node_user -->|"submits command"| node_cli
node_user -->|"submits request"| node_gui
node_user -->|"starts conversation"| node_chatbot
node_cli -->|"dispatches"| node_core
node_gui -->|"uses engine"| node_core
node_chatbot -->|"sends turns"| node_core
node_core -->|"analyzes intent"| node_nlp
node_core -->|"parses command"| node_parser
node_core -.->|"requests plan"| node_planner
node_core -->|"executes workflow"| node_workflow
node_workflow -->|"dispatches capability"| node_plugin_mgr
node_core -->|"queries plugins"| node_plugin_mgr
node_plugin_mgr -->|"loads and executes"| node_plugins
node_plugin_mgr -->|"resolves capability"| node_capabilities
node_workflow -->|"performs OS actions"| node_adapters
node_workflow -.->|"checks permissions"| node_security
node_adapters -->|"operates on"| node_operating_system
node_plugins -.->|"provides file actions"| node_native
node_plugins -->|"routes workflow requests"| node_n8n
node_n8n -->|"calls REST API"| node_n8n_service
node_triggers -->|"polls and receives callbacks"| node_n8n_service
node_core -->|"builds distro"| node_distro
node_distro -->|"builds ISO"| node_build_tools
node_planner -->|"requests completion"| node_models
node_chatbot -.->|"maintains turns"| node_context
node_models -->|"sends model requests"| node_openrouter
node_openrouter -->|"returns completions"| node_models

click node_cli "https://github.com/grim-sudo/automation/blob/master/archon/_cli.py"
click node_gui "https://github.com/grim-sudo/automation/blob/master/archon/ui/gui/app.py"
click node_chatbot "https://github.com/grim-sudo/automation/blob/master/archon/ui/chatbot.py"
click node_core "https://github.com/grim-sudo/automation/blob/master/archon/core/engine.py"
click node_nlp "https://github.com/grim-sudo/automation/blob/master/archon/nlp/semantic_engine.py"
click node_parser "https://github.com/grim-sudo/automation/blob/master/archon/parsers/command_parser.py"
click node_workflow "https://github.com/grim-sudo/automation/blob/master/archon/workflow/engine.py"
click node_plugin_mgr "https://github.com/grim-sudo/automation/blob/master/archon/core/plugin_manager.py"
click node_capabilities "https://github.com/grim-sudo/automation/blob/master/archon/capabilities/registry.py"
click node_native "https://github.com/grim-sudo/automation/blob/master/archon/capabilities/native/filesystem.py"
click node_plugins "https://github.com/grim-sudo/automation/tree/master/archon/plugins"
click node_adapters "https://github.com/grim-sudo/automation/blob/master/archon/os_adapters/adapter_factory.py"
click node_security "https://github.com/grim-sudo/automation/blob/master/archon/security/permission_manager.py"
click node_n8n "https://github.com/grim-sudo/automation/blob/master/archon/plugins/n8n_bridge/workflow_manager.py"
click node_triggers "https://github.com/grim-sudo/automation/blob/master/archon/plugins/n8n_bridge/trigger_engine.py"
click node_distro "https://github.com/grim-sudo/automation/blob/master/archon/distro_builder/build_pipeline.py"
click node_planner "https://github.com/grim-sudo/automation/blob/master/archon/ai/task_planner.py"
click node_models "https://github.com/grim-sudo/automation/blob/master/archon/ai/model_manager.py"
click node_context "https://github.com/grim-sudo/automation/blob/master/archon/ai/context_manager.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_gui,node_chatbot,node_user toneBlue
class node_core,node_nlp,node_parser,node_workflow,node_plugin_mgr toneAmber
class node_capabilities,node_native,node_plugins,node_adapters,node_security,node_openrouter toneMint
class node_n8n,node_triggers,node_distro toneRose
class node_planner,node_models,node_context,node_n8n_service,node_operating_system,node_build_tools toneIndigo
```

## Components

### User interfaces

- [Unified CLI](https://github.com/grim-sudo/automation/blob/master/archon/_cli.py): `archon/_cli.py`
- [GUI application](https://github.com/grim-sudo/automation/blob/master/archon/ui/gui/app.py): `archon/ui/gui/app.py`
- [Chatbot](https://github.com/grim-sudo/automation/blob/master/archon/ui/chatbot.py): `archon/ui/chatbot.py`

### Intent and orchestration

- [Core engine](https://github.com/grim-sudo/automation/blob/master/archon/core/engine.py): `archon/core/engine.py`
- [Semantic NLP](https://github.com/grim-sudo/automation/blob/master/archon/nlp/semantic_engine.py): `archon/nlp/semantic_engine.py`
- [Command parser](https://github.com/grim-sudo/automation/blob/master/archon/parsers/command_parser.py): `archon/parsers/command_parser.py`
- [Workflow engine](https://github.com/grim-sudo/automation/blob/master/archon/workflow/engine.py): `archon/workflow/engine.py`
- [Plugin manager](https://github.com/grim-sudo/automation/blob/master/archon/core/plugin_manager.py): `archon/core/plugin_manager.py`

### Automation capabilities

- [Capability registry](https://github.com/grim-sudo/automation/blob/master/archon/capabilities/registry.py): `archon/capabilities/registry.py`
- [File and document actions](https://github.com/grim-sudo/automation/blob/master/archon/capabilities/native/filesystem.py): `archon/capabilities/native/filesystem.py`
- [Automation plugins](https://github.com/grim-sudo/automation/tree/master/archon/plugins): `archon/plugins`
- [OS adapters](https://github.com/grim-sudo/automation/blob/master/archon/os_adapters/adapter_factory.py): `archon/os_adapters/adapter_factory.py`
- [Permission controls](https://github.com/grim-sudo/automation/blob/master/archon/security/permission_manager.py): `archon/security/permission_manager.py`

### Specialized workflows

- [n8n workflow bridge](https://github.com/grim-sudo/automation/blob/master/archon/plugins/n8n_bridge/workflow_manager.py): `archon/plugins/n8n_bridge/workflow_manager.py`
- [Execution triggers](https://github.com/grim-sudo/automation/blob/master/archon/plugins/n8n_bridge/trigger_engine.py): `archon/plugins/n8n_bridge/trigger_engine.py`
- [ISO build pipeline](https://github.com/grim-sudo/automation/blob/master/archon/distro_builder/build_pipeline.py): `archon/distro_builder/build_pipeline.py`

### AI services

- [AI task planner](https://github.com/grim-sudo/automation/blob/master/archon/ai/task_planner.py): `archon/ai/task_planner.py`
- [Model manager](https://github.com/grim-sudo/automation/blob/master/archon/ai/model_manager.py): `archon/ai/model_manager.py`
- [Conversation context](https://github.com/grim-sudo/automation/blob/master/archon/ai/context_manager.py): `archon/ai/context_manager.py`

### Other components

- **User**
- **OpenRouter API**
- **n8n service**
- **Host operating system**
- **Kernel and ISO tools**

## Connections

- User → Unified CLI: submits command
- User → GUI application: submits request
- User → Chatbot: starts conversation
- Unified CLI → Core engine: dispatches
- GUI application → Core engine: uses engine
- Chatbot → Core engine: sends turns
- Core engine → Semantic NLP: analyzes intent
- Core engine → Command parser: parses command
- Core engine → AI task planner: requests plan
- Core engine → Workflow engine: executes workflow
- Workflow engine → Plugin manager: dispatches capability
- Core engine → Plugin manager: queries plugins
- Plugin manager → Automation plugins: loads and executes
- Plugin manager → Capability registry: resolves capability
- Workflow engine → OS adapters: performs OS actions
- Workflow engine → Permission controls: checks permissions
- OS adapters → Host operating system: operates on
- Automation plugins → File and document actions: provides file actions
- Automation plugins → n8n workflow bridge: routes workflow requests
- n8n workflow bridge → n8n service: calls REST API
- Execution triggers → n8n service: polls and receives callbacks
- Core engine → ISO build pipeline: builds distro
- ISO build pipeline → Kernel and ISO tools: builds ISO
- AI task planner → Model manager: requests completion
- Chatbot → Conversation context: maintains turns
- Model manager → OpenRouter API: sends model requests
- OpenRouter API → Model manager: returns completions