# weiykong/smart-translator-for-macos architecture

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

- Interactive diagram: https://gitdiagram.com/weiykong/smart-translator-for-macos
- Repository: https://github.com/weiykong/smart-translator-for-macos

## Overview

Smart Translator is a macOS menu-bar clipboard assistant. Users select text or copy it, invoke correction with a global hotkey or choose an action from the menu, and paste the processed result. The main app owns configuration, action dispatch, asynchronous work, clipboard updates, and notifications; processing can use Ollama or Gemini, with Playwright as an optional Gemini transport. The source excerpt is partial, so some capability links rely on README documentation rather than inspected implementations.

Main entry points: [`smart_translator_dynamic.py`](https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py) (App Controller), [`gemini_playwright_bridge.py`](https://github.com/weiykong/smart-translator-for-macos/blob/main/gemini_playwright_bridge.py) (Playwright Bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Menu Bar Interface"]
  node_app["App Controller"]
  node_hotkey["Global Hotkey"]
  node_menu["Action Menu"]
end

subgraph group_actions["Text Actions"]
  node_correct["Smart Correction"]
  node_translate["Translation"]
  node_skills["Custom Skills"]
  node_token["Token Saver"]
end

subgraph group_providers["Model Providers"]
  node_provider["Provider Dispatch"]
  node_ollama["Ollama Client"]
  node_gemini["Gemini Client"]
  node_bridge["Playwright Bridge"]
end

subgraph group_state["App State"]
  node_config[("App Config")]
  node_history["Clipboard History"]
  node_models["Model Selection"]
end

node_user(("User"))
node_clipboard["System Clipboard"]
node_ollama_service["Ollama Service"]
node_gemini_api["Gemini API"]
node_browser["Gemini Web"]
node_result["Paste Result"]

node_user -->|"presses"| node_hotkey
node_user -->|"chooses action"| node_menu
node_hotkey -->|"dispatches"| node_app
node_menu -->|"dispatches"| node_app
node_app -->|"reads text"| node_clipboard
node_app -->|"runs action"| node_correct
node_app -->|"runs action"| node_translate
node_app -->|"runs action"| node_skills
node_app -->|"runs action"| node_token
node_correct -->|"requests generation"| node_provider
node_translate -->|"requests generation"| node_provider
node_skills -->|"requests generation"| node_provider
node_token -.->|"requests generation"| node_provider
node_provider -->|"selects provider"| node_ollama
node_provider -->|"selects provider"| node_gemini
node_ollama -->|"HTTP requests"| node_ollama_service
node_gemini -->|"REST requests"| node_gemini_api
node_gemini -.->|"invokes fallback"| node_bridge
node_bridge -.->|"submits prompt"| node_browser
node_app -->|"reads and writes"| node_config
node_app -->|"stores clipboard states"| node_history
node_app -->|"refreshes selection"| node_models
node_models -->|"fetches models"| node_ollama
node_models -->|"refreshes models"| node_gemini_api
node_app -->|"writes result"| node_clipboard
node_clipboard -->|"supplies for paste"| node_result
node_user -->|"pastes"| node_result

click node_app "https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py"
click node_hotkey "https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py"
click node_menu "https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py"
click node_correct "https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py"
click node_translate "https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py"
click node_skills "https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py"
click node_token "https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py"
click node_provider "https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py"
click node_ollama "https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py"
click node_gemini "https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py"
click node_bridge "https://github.com/weiykong/smart-translator-for-macos/blob/main/gemini_playwright_bridge.py"
click node_config "https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py"
click node_history "https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py"
click node_models "https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.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_app,node_hotkey,node_menu,node_user toneBlue
class node_correct,node_translate,node_skills,node_token toneAmber
class node_provider,node_ollama,node_gemini,node_bridge,node_gemini_api toneMint
class node_config,node_history,node_models toneRose
class node_clipboard,node_ollama_service,node_browser,node_result toneIndigo
```

## Components

### Menu Bar Interface

- [App Controller](https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py): `smart_translator_dynamic.py`
- [Global Hotkey](https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py): `smart_translator_dynamic.py`
- [Action Menu](https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py): `smart_translator_dynamic.py`

### Text Actions

- [Smart Correction](https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py): `smart_translator_dynamic.py`
- [Translation](https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py): `smart_translator_dynamic.py`
- [Custom Skills](https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py): `smart_translator_dynamic.py`
- [Token Saver](https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py): `smart_translator_dynamic.py`

### Model Providers

- [Provider Dispatch](https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py): `smart_translator_dynamic.py`
- [Ollama Client](https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py): `smart_translator_dynamic.py`
- [Gemini Client](https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py): `smart_translator_dynamic.py`
- [Playwright Bridge](https://github.com/weiykong/smart-translator-for-macos/blob/main/gemini_playwright_bridge.py): `gemini_playwright_bridge.py`

### App State

- [App Config](https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py): `smart_translator_dynamic.py`
- [Clipboard History](https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py): `smart_translator_dynamic.py`
- [Model Selection](https://github.com/weiykong/smart-translator-for-macos/blob/main/smart_translator_dynamic.py): `smart_translator_dynamic.py`

### Other components

- **User**
- **System Clipboard**
- **Ollama Service**
- **Gemini API**
- **Gemini Web**
- **Paste Result**

## Connections

- User → Global Hotkey: presses
- User → Action Menu: chooses action
- Global Hotkey → App Controller: dispatches
- Action Menu → App Controller: dispatches
- App Controller → System Clipboard: reads text
- App Controller → Smart Correction: runs action
- App Controller → Translation: runs action
- App Controller → Custom Skills: runs action
- App Controller → Token Saver: runs action
- Smart Correction → Provider Dispatch: requests generation
- Translation → Provider Dispatch: requests generation
- Custom Skills → Provider Dispatch: requests generation
- Token Saver → Provider Dispatch: requests generation
- Provider Dispatch → Ollama Client: selects provider
- Provider Dispatch → Gemini Client: selects provider
- Ollama Client → Ollama Service: HTTP requests
- Gemini Client → Gemini API: REST requests
- Gemini Client → Playwright Bridge: invokes fallback
- Playwright Bridge → Gemini Web: submits prompt
- App Controller → App Config: reads and writes
- App Controller → Clipboard History: stores clipboard states
- App Controller → Model Selection: refreshes selection
- Model Selection → Ollama Client: fetches models
- Model Selection → Gemini API: refreshes models
- App Controller → System Clipboard: writes result
- System Clipboard → Paste Result: supplies for paste
- User → Paste Result: pastes