# hello-qm/catgo-lrg architecture

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

- Interactive diagram: https://gitdiagram.com/hello-qm/catgo-lrg
- Repository: https://github.com/hello-qm/catgo-lrg

## Overview

CatGo is an AI workbench for computational materials science. A researcher opens or builds a structure, inspects and edits it, prepares calculation inputs or a visual workflow, and can submit and monitor work on their own HPC environment before reviewing scientific results. The repository combines desktop UI, Python services, scientific extensions, and workflow runtimes. The graph preserves the README’s major capabilities; unsampled feature links are documented at the product level rather than inferred from directory names.

Main entry points: [`server/catgo/routers/workflow_engine.py`](https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/routers/workflow_engine.py) (Workflow API), [`server/catgo/routers/workflow_engine_tasks.py`](https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/routers/workflow_engine_tasks.py) (Task API), [`server/catgo/workflow/engine/lifecycle.py`](https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/workflow/engine/lifecycle.py) (Workflow Lifecycle), [`desktop/App.svelte`](https://github.com/hello-qm/catgo-lrg/blob/main/desktop/App.svelte) (Desktop Workbench)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workbench["Research Workbench"]
  node_desktop["Desktop Workbench<br/>[App.svelte]"]
  node_pane_layout["Pane Layout<br/>[pane-tree.ts]"]
end

subgraph group_science["Structure Science"]
  node_structure_editor["Structure Editor"]
  node_structure_operations["Structure Operations<br/>[structure_ops.py]"]
  node_ferrox["Ferrox Algorithms<br/>[structure.rs]"]
end

subgraph group_workflow["Workflow Execution"]
  node_input_preparation["Input Preparation<br/>[build.py]"]
  node_workflow_editor["Workflow Editor"]
  node_workflow_api["Workflow API<br/>[workflow_engine.py]"]
  node_task_api["Task API"]
  node_workflow_service["Workflow Service<br/>[service.py]"]
  node_workflow_store[("Workflow State Store<br/>[db.py]")]
  node_workflow_lifecycle["Workflow Lifecycle<br/>[lifecycle.py]"]
  node_engine_runtime["Calculation Engines<br/>[engine_builtins.py]"]
end

subgraph group_services["Services And AI"]
  node_hpc["HPC Access<br/>[hpc_client.py]"]
  node_catbot["CatBot Tools<br/>[server.py]"]
  node_plugin_system["Plugin System<br/>[manager.py]"]
end

subgraph group_analysis["Scientific Analysis"]
  node_results["Results And Monitoring<br/>[job_parser.py]"]
  node_analysis_tools["Analysis Tools<br/>[dos.py]"]
  node_catalysis["Catalysis Analysis<br/>[energy_diagram.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"uses"| node_desktop
node_desktop -->|"manages panes"| node_pane_layout
node_researcher -->|"edits structures"| node_structure_editor
node_researcher -->|"builds models"| node_structure_operations
node_structure_operations -.->|"uses algorithms"| node_ferrox
node_researcher -->|"prepares inputs"| node_input_preparation
node_researcher -->|"edits workflows"| node_workflow_editor
node_workflow_editor -->|"loads task"| node_task_api
node_researcher -->|"submits workflow"| node_workflow_api
node_workflow_api -->|"delegates actions"| node_workflow_service
node_workflow_service -->|"reads and writes"| node_workflow_store
node_workflow_lifecycle -.->|"persists state"| node_workflow_store
node_workflow_lifecycle -.->|"dispatches tasks"| node_engine_runtime
node_engine_runtime -.->|"runs remotely"| node_hpc
node_researcher -->|"connects remotely"| node_hpc
node_workflow_api -.->|"exposes task actions"| node_task_api
node_task_api -->|"parses convergence"| node_results
node_researcher -->|"requests by chat"| node_catbot
node_researcher -->|"extends tools"| node_plugin_system
node_researcher -->|"analyzes properties"| node_analysis_tools
node_researcher -->|"reviews catalysis"| node_catalysis

click node_desktop "https://github.com/hello-qm/catgo-lrg/blob/main/desktop/App.svelte"
click node_pane_layout "https://github.com/hello-qm/catgo-lrg/blob/main/desktop/pane-tree.ts"
click node_structure_editor "https://github.com/hello-qm/catgo-lrg/blob/main/src/lib/structure/atoms/atom-manager.svelte.ts"
click node_structure_operations "https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/routers/structure_ops.py"
click node_ferrox "https://github.com/hello-qm/catgo-lrg/blob/main/extensions/rust/src/structure.rs"
click node_input_preparation "https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/routers/build.py"
click node_workflow_editor "https://github.com/hello-qm/catgo-lrg/blob/main/src/lib/workflow/EngineTaskEditor.svelte"
click node_workflow_api "https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/routers/workflow_engine.py"
click node_task_api "https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/routers/workflow_engine_tasks.py"
click node_workflow_service "https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/workflow/service.py"
click node_workflow_store "https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/workflow/db.py"
click node_workflow_lifecycle "https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/workflow/engine/lifecycle.py"
click node_engine_runtime "https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/workflow/engine/engine_builtins.py"
click node_hpc "https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/utils/hpc_client.py"
click node_catbot "https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/mcp_tools/server.py"
click node_plugin_system "https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/plugins/manager.py"
click node_results "https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/utils/job_parser.py"
click node_analysis_tools "https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/routers/dos.py"
click node_catalysis "https://github.com/hello-qm/catgo-lrg/blob/main/server/workflow/catalysis/energy_diagram.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_desktop,node_pane_layout toneBlue
class node_structure_editor,node_structure_operations,node_ferrox toneAmber
class node_input_preparation,node_workflow_editor,node_workflow_api,node_task_api,node_workflow_service,node_workflow_store,node_workflow_lifecycle,node_engine_runtime toneMint
class node_hpc,node_catbot,node_plugin_system toneRose
class node_results,node_analysis_tools,node_catalysis,node_researcher toneIndigo
```

## Components

### Research Workbench

- [Desktop Workbench](https://github.com/hello-qm/catgo-lrg/blob/main/desktop/App.svelte): `desktop/App.svelte`
- [Pane Layout](https://github.com/hello-qm/catgo-lrg/blob/main/desktop/pane-tree.ts): `desktop/pane-tree.ts`

### Structure Science

- [Structure Editor](https://github.com/hello-qm/catgo-lrg/blob/main/src/lib/structure/atoms/atom-manager.svelte.ts): `src/lib/structure/atoms/atom-manager.svelte.ts`
- [Structure Operations](https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/routers/structure_ops.py): `server/catgo/routers/structure_ops.py`
- [Ferrox Algorithms](https://github.com/hello-qm/catgo-lrg/blob/main/extensions/rust/src/structure.rs): `extensions/rust/src/structure.rs`

### Workflow Execution

- [Input Preparation](https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/routers/build.py): `server/catgo/routers/build.py`
- [Workflow Editor](https://github.com/hello-qm/catgo-lrg/blob/main/src/lib/workflow/EngineTaskEditor.svelte): `src/lib/workflow/EngineTaskEditor.svelte`
- [Workflow API](https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/routers/workflow_engine.py): `server/catgo/routers/workflow_engine.py`
- [Task API](https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/routers/workflow_engine_tasks.py): `server/catgo/routers/workflow_engine_tasks.py`
- [Workflow Service](https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/workflow/service.py): `server/catgo/workflow/service.py`
- [Workflow State Store](https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/workflow/db.py): `server/catgo/workflow/db.py`
- [Workflow Lifecycle](https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/workflow/engine/lifecycle.py): `server/catgo/workflow/engine/lifecycle.py`
- [Calculation Engines](https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/workflow/engine/engine_builtins.py): `server/catgo/workflow/engine/engine_builtins.py`

### Services And AI

- [HPC Access](https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/utils/hpc_client.py): `server/catgo/utils/hpc_client.py`
- [CatBot Tools](https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/mcp_tools/server.py): `server/catgo/mcp_tools/server.py`
- [Plugin System](https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/plugins/manager.py): `server/catgo/plugins/manager.py`

### Scientific Analysis

- [Results And Monitoring](https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/utils/job_parser.py): `server/catgo/utils/job_parser.py`
- [Analysis Tools](https://github.com/hello-qm/catgo-lrg/blob/main/server/catgo/routers/dos.py): `server/catgo/routers/dos.py`
- [Catalysis Analysis](https://github.com/hello-qm/catgo-lrg/blob/main/server/workflow/catalysis/energy_diagram.py): `server/workflow/catalysis/energy_diagram.py`

### Other components

- **Researcher**

## Connections

- Researcher → Desktop Workbench: uses
- Desktop Workbench → Pane Layout: manages panes (evidence: `desktop/App.svelte`)
- Researcher → Structure Editor: edits structures
- Researcher → Structure Operations: builds models
- Structure Operations → Ferrox Algorithms: uses algorithms
- Researcher → Input Preparation: prepares inputs
- Researcher → Workflow Editor: edits workflows
- Workflow Editor → Task API: loads task (evidence: `src/lib/workflow/EngineTaskEditor.svelte`)
- Researcher → Workflow API: submits workflow
- Workflow API → Workflow Service: delegates actions (evidence: `server/catgo/routers/workflow_engine.py`)
- Workflow Service → Workflow State Store: reads and writes (evidence: `server/catgo/workflow/service.py`)
- Workflow Lifecycle → Workflow State Store: persists state
- Workflow Lifecycle → Calculation Engines: dispatches tasks
- Calculation Engines → HPC Access: runs remotely
- Researcher → HPC Access: connects remotely
- Workflow API → Task API: exposes task actions
- Task API → Results And Monitoring: parses convergence (evidence: `server/catgo/routers/workflow_engine_tasks.py`)
- Researcher → CatBot Tools: requests by chat
- Researcher → Plugin System: extends tools
- Researcher → Analysis Tools: analyzes properties
- Researcher → Catalysis Analysis: reviews catalysis
