# yuxuan1123/octools architecture

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

- Interactive diagram: https://gitdiagram.com/yuxuan1123/octools
- Repository: https://github.com/yuxuan1123/octools

## Overview

OCTools is a PySide6 desktop toolbox for document conversion and merging, offline translation and speech, and screen-oriented utilities. A user starts the application, selects a built-in tool, supplies files or text, and receives converted or generated output. Conversion is the clearest evidenced workflow: the conversion service tries a registered direct converter, then asks the star router for a fallback route and runs its hops. The README also documents OCR, speech, directory-tree, color-picker, and external-plugin capabilities. The supplied tree omits several README-described UI and translation modules, so their wiring is not inferred here.

Main entry points: [`services/conversion/pipeline.py`](https://github.com/yuxuan1123/octools/blob/main/services/conversion/pipeline.py) (Conversion pipeline), [`main.py`](https://github.com/yuxuan1123/octools/blob/main/main.py) (Application startup), [`services/conversion/registry.py`](https://github.com/yuxuan1123/octools/blob/main/services/conversion/registry.py) (Format registry), [`plugins/conversion/runner.py`](https://github.com/yuxuan1123/octools/blob/main/plugins/conversion/runner.py) (Conversion runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_startup["Application startup<br/>[main.py]"]
  node_ui["Desktop interface<br/>[__init__.py]"]
  node_config["Business settings"]
end

subgraph group_conversion["Conversion"]
  node_converter_tab["Conversion tool<br/>[tab_conversion.py]"]
  node_convert_runner["Conversion runner<br/>[runner.py]"]
  node_pipeline["Conversion pipeline<br/>[pipeline.py]"]
  node_registry["Format registry<br/>[registry.py]"]
  node_router["Fallback router<br/>[router.py]"]
  node_star_runner["Route executor<br/>[runner.py]"]
  node_format_meta["Format metadata<br/>[registry.py]"]
end

subgraph group_media["AI and media"]
  node_document["Document conversion<br/>[document_engine.py]"]
  node_presentation["Presentation conversion"]
  node_md_docx["Formatted Markdown DOCX<br/>[md_docx_engine.py]"]
  node_translation["Offline translation"]
  node_tts["Speech synthesis<br/>[tts_engine.py]"]
end

subgraph group_tools["Built-in tools"]
  node_merge["File merging<br/>[runner.py]"]
  node_tree["Directory tree<br/>[tab_tree.py]"]
  node_color["Screen color picker<br/>[tab_color_pick.py]"]
  node_terminal["Terminal tool<br/>[tab_terminal.py]"]
end

subgraph group_ext["External plugins"]
  node_plugin_mgr["Plugin manager<br/>[manager.py]"]
  node_plugin_process["Plugin subprocesses"]
  node_plugin["External plugin"]
end

node_user(("Desktop user"))
node_local_files["Local files"]

node_user -->|"launches"| node_startup
node_startup -->|"opens interface"| node_ui
node_startup -->|"starts manager"| node_plugin_mgr
node_user -->|"selects tool"| node_converter_tab
node_converter_tab -->|"starts conversion"| node_convert_runner
node_convert_runner -->|"calls"| node_pipeline
node_pipeline -->|"checks direct route"| node_registry
node_pipeline -->|"requests fallback path"| node_router
node_pipeline -->|"executes fallback"| node_star_runner
node_router -->|"reads converter edges"| node_registry
node_registry -->|"uses format metadata"| node_format_meta
node_star_runner -->|"looks up each hop"| node_registry
node_pipeline -->|"dispatches registered conversion"| node_document
node_pipeline -->|"dispatches registered conversion"| node_presentation
node_pipeline -->|"dispatches registered conversion"| node_md_docx
node_user -->|"provides input"| node_local_files
node_convert_runner -->|"reads and writes"| node_local_files
node_startup -->|"loads settings"| node_config
node_startup -->|"preloads models"| node_translation
node_user -->|"selects tool"| node_merge
node_user -->|"selects tool"| node_tree
node_user -->|"selects tool"| node_color
node_user -->|"selects tool"| node_terminal
node_plugin_mgr -->|"manages lifecycle"| node_plugin_process
node_plugin_mgr -->|"discovers and dispatches"| node_plugin
node_plugin_process -.->|"communicates by IPC"| node_plugin

click node_startup "https://github.com/yuxuan1123/octools/blob/main/main.py"
click node_ui "https://github.com/yuxuan1123/octools/blob/main/ui/__init__.py"
click node_config "https://github.com/yuxuan1123/octools/tree/main/config"
click node_converter_tab "https://github.com/yuxuan1123/octools/blob/main/plugins/conversion/tab_conversion.py"
click node_convert_runner "https://github.com/yuxuan1123/octools/blob/main/plugins/conversion/runner.py"
click node_pipeline "https://github.com/yuxuan1123/octools/blob/main/services/conversion/pipeline.py"
click node_registry "https://github.com/yuxuan1123/octools/blob/main/services/conversion/registry.py"
click node_router "https://github.com/yuxuan1123/octools/blob/main/services/conversion/star/router.py"
click node_star_runner "https://github.com/yuxuan1123/octools/blob/main/services/conversion/star/runner.py"
click node_format_meta "https://github.com/yuxuan1123/octools/blob/main/core/formats/registry.py"
click node_document "https://github.com/yuxuan1123/octools/blob/main/core/engines/document_engine.py"
click node_presentation "https://github.com/yuxuan1123/octools/blob/main/core/engines/presentation_engine.py"
click node_md_docx "https://github.com/yuxuan1123/octools/blob/main/core/engines/md_docx_engine.py"
click node_translation "https://github.com/yuxuan1123/octools/blob/main/core/engines/translation_engine.py"
click node_tts "https://github.com/yuxuan1123/octools/blob/main/core/engines/tts_engine.py"
click node_merge "https://github.com/yuxuan1123/octools/blob/main/plugins/merge/runner.py"
click node_tree "https://github.com/yuxuan1123/octools/blob/main/plugins/tree/tab_tree.py"
click node_color "https://github.com/yuxuan1123/octools/blob/main/plugins/color_pick/tab_color_pick.py"
click node_terminal "https://github.com/yuxuan1123/octools/blob/main/plugins/terminal/tab_terminal.py"
click node_plugin_mgr "https://github.com/yuxuan1123/octools/blob/main/services/ext_plugins/manager.py"
click node_plugin_process "https://github.com/yuxuan1123/octools/tree/main/services/ext_plugins"

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_startup,node_ui,node_config,node_user toneBlue
class node_converter_tab,node_convert_runner,node_pipeline,node_registry,node_router,node_star_runner,node_format_meta toneAmber
class node_document,node_presentation,node_md_docx,node_translation,node_tts toneMint
class node_merge,node_tree,node_color,node_terminal toneRose
class node_plugin_mgr,node_plugin_process,node_plugin,node_local_files toneIndigo
```

## Components

### Application

- [Application startup](https://github.com/yuxuan1123/octools/blob/main/main.py): `main.py`
- [Desktop interface](https://github.com/yuxuan1123/octools/blob/main/ui/__init__.py): `ui/__init__.py`
- [Business settings](https://github.com/yuxuan1123/octools/tree/main/config): `config`

### Conversion

- [Conversion tool](https://github.com/yuxuan1123/octools/blob/main/plugins/conversion/tab_conversion.py): `plugins/conversion/tab_conversion.py`
- [Conversion runner](https://github.com/yuxuan1123/octools/blob/main/plugins/conversion/runner.py): `plugins/conversion/runner.py`
- [Conversion pipeline](https://github.com/yuxuan1123/octools/blob/main/services/conversion/pipeline.py): `services/conversion/pipeline.py`
- [Format registry](https://github.com/yuxuan1123/octools/blob/main/services/conversion/registry.py): `services/conversion/registry.py`
- [Fallback router](https://github.com/yuxuan1123/octools/blob/main/services/conversion/star/router.py): `services/conversion/star/router.py`
- [Route executor](https://github.com/yuxuan1123/octools/blob/main/services/conversion/star/runner.py): `services/conversion/star/runner.py`
- [Format metadata](https://github.com/yuxuan1123/octools/blob/main/core/formats/registry.py): `core/formats/registry.py`

### AI and media

- [Document conversion](https://github.com/yuxuan1123/octools/blob/main/core/engines/document_engine.py): `core/engines/document_engine.py`
- [Presentation conversion](https://github.com/yuxuan1123/octools/blob/main/core/engines/presentation_engine.py): `core/engines/presentation_engine.py`
- [Formatted Markdown DOCX](https://github.com/yuxuan1123/octools/blob/main/core/engines/md_docx_engine.py): `core/engines/md_docx_engine.py`
- [Offline translation](https://github.com/yuxuan1123/octools/blob/main/core/engines/translation_engine.py): `core/engines/translation_engine.py`
- [Speech synthesis](https://github.com/yuxuan1123/octools/blob/main/core/engines/tts_engine.py): `core/engines/tts_engine.py`

### Built-in tools

- [File merging](https://github.com/yuxuan1123/octools/blob/main/plugins/merge/runner.py): `plugins/merge/runner.py`
- [Directory tree](https://github.com/yuxuan1123/octools/blob/main/plugins/tree/tab_tree.py): `plugins/tree/tab_tree.py`
- [Screen color picker](https://github.com/yuxuan1123/octools/blob/main/plugins/color_pick/tab_color_pick.py): `plugins/color_pick/tab_color_pick.py`
- [Terminal tool](https://github.com/yuxuan1123/octools/blob/main/plugins/terminal/tab_terminal.py): `plugins/terminal/tab_terminal.py`

### External plugins

- [Plugin manager](https://github.com/yuxuan1123/octools/blob/main/services/ext_plugins/manager.py): `services/ext_plugins/manager.py`
- [Plugin subprocesses](https://github.com/yuxuan1123/octools/tree/main/services/ext_plugins): `services/ext_plugins`
- **External plugin**

### Other components

- **Desktop user**
- **Local files**

## Connections

- Desktop user → Application startup: launches
- Application startup → Desktop interface: opens interface
- Application startup → Plugin manager: starts manager
- Desktop user → Conversion tool: selects tool
- Conversion tool → Conversion runner: starts conversion
- Conversion runner → Conversion pipeline: calls
- Conversion pipeline → Format registry: checks direct route
- Conversion pipeline → Fallback router: requests fallback path
- Conversion pipeline → Route executor: executes fallback
- Fallback router → Format registry: reads converter edges
- Format registry → Format metadata: uses format metadata
- Route executor → Format registry: looks up each hop
- Conversion pipeline → Document conversion: dispatches registered conversion
- Conversion pipeline → Presentation conversion: dispatches registered conversion
- Conversion pipeline → Formatted Markdown DOCX: dispatches registered conversion
- Desktop user → Local files: provides input
- Conversion runner → Local files: reads and writes
- Application startup → Business settings: loads settings
- Application startup → Offline translation: preloads models
- Desktop user → File merging: selects tool
- Desktop user → Directory tree: selects tool
- Desktop user → Screen color picker: selects tool
- Desktop user → Terminal tool: selects tool
- Plugin manager → Plugin subprocesses: manages lifecycle
- Plugin manager → External plugin: discovers and dispatches
- Plugin subprocesses → External plugin: communicates by IPC