# dinhphu-0124/mackey architecture

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

- Interactive diagram: https://gitdiagram.com/dinhphu-0124/mackey
- Repository: https://github.com/dinhphu-0124/mackey

## Overview

MacKey is a macOS Vietnamese input method with a companion settings and utility interface. The main workflow is a user typing in another application, with the engine transforming keystrokes into Vietnamese text according to the selected input style and encoding. Users configure typing behavior in the dashboard; separate capabilities include macro management and suggestions, text conversion, and release updates. Engine internals are represented where excerpts identify them. UI-to-engine wiring and several UI implementations were not sampled, so those links are marked unverified.

Main entry points: [`Source/Sources/MacKey/engine/Engine.cpp`](https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/engine/Engine.cpp) (Key Event Engine), [`Source/Sources/MacKey/macOS/ModernKey/AppDelegate.m`](https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/macOS/ModernKey/AppDelegate.m) (Menu Bar), [`Source/Sources/MacKey/macOS/ModernKey/MacroViewController.mm`](https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/macOS/ModernKey/MacroViewController.mm) (Macro Manager), [`Source/Sources/MacKey/macOS/ModernKey/ViewController.m`](https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/macOS/ModernKey/ViewController.m) (Settings Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["App Interface"]
  node_menu["Menu Bar<br/>[AppDelegate.m]"]
  node_dashboard["Settings Dashboard<br/>[ViewController.m]"]
  node_macro_ui["Macro Manager"]
  node_suggest_ui["Macro Suggestions"]
  node_convert_ui["Convert Window"]
  node_about["About and Updates"]
end

subgraph group_typing["Typing Engine"]
  node_engine["Key Event Engine<br/>[Engine.cpp]"]
  node_rules["Vietnamese Rules<br/>[Vietnamese.cpp]"]
  node_types["Key Types and Codes<br/>[DataType.h]"]
  node_macro["Macro Runtime<br/>[Macro.cpp]"]
end

subgraph group_utilities["Text Utilities"]
  node_conversion["Conversion Engine<br/>[ConvertTool.cpp]"]
  node_xlsx_parser["XLSX Import<br/>[xlsx_parser.py]"]
  node_xlsx_exporter["XLSX Export<br/>[xlsx_exporter.py]"]
end

subgraph group_services["App Services"]
  node_manager["App Manager<br/>[MacKeyManager.m]"]
  node_switching["Smart Switching<br/>[SmartSwitchKey.cpp]"]
end

node_user(("User"))
node_target["Text Application"]
node_github["GitHub Releases API"]

node_user -->|"opens controls"| node_menu
node_user -->|"types text"| node_target
node_menu -->|"opens settings"| node_dashboard
node_menu -->|"opens manager"| node_macro_ui
node_menu -->|"opens converter"| node_convert_ui
node_menu -->|"opens about"| node_about
node_about -->|"checks releases"| node_github
node_target -.->|"sends keystrokes"| node_engine
node_engine -.->|"replaces text"| node_target
node_engine -->|"uses rules"| node_rules
node_engine -->|"uses definitions"| node_types
node_engine -.->|"checks suggestions"| node_macro
node_suggest_ui -.->|"shows suggestions"| node_macro
node_dashboard -.->|"configures switching"| node_switching
node_convert_ui -.->|"requests conversion"| node_conversion
node_macro_ui -->|"imports macros"| node_xlsx_parser
node_macro_ui -->|"exports macros"| node_xlsx_exporter
node_manager -.->|"manages engine"| node_engine

click node_menu "https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/macOS/ModernKey/AppDelegate.m"
click node_dashboard "https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/macOS/ModernKey/ViewController.m"
click node_macro_ui "https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/macOS/ModernKey/MacroViewController.mm"
click node_suggest_ui "https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/macOS/ModernKey/MacroSuggestionController.mm"
click node_convert_ui "https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/macOS/ModernKey/ConvertToolViewController.mm"
click node_about "https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/macOS/ModernKey/AboutViewController.m"
click node_manager "https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/macOS/ModernKey/MacKeyManager.m"
click node_engine "https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/engine/Engine.cpp"
click node_rules "https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/engine/Vietnamese.cpp"
click node_types "https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/engine/DataType.h"
click node_macro "https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/engine/Macro.cpp"
click node_switching "https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/engine/SmartSwitchKey.cpp"
click node_conversion "https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/engine/ConvertTool.cpp"
click node_xlsx_parser "https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/macOS/ModernKey/xlsx_parser.py"
click node_xlsx_exporter "https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/macOS/ModernKey/xlsx_exporter.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_menu,node_dashboard,node_macro_ui,node_suggest_ui,node_convert_ui,node_about,node_user toneBlue
class node_engine,node_rules,node_types,node_macro toneAmber
class node_conversion,node_xlsx_parser,node_xlsx_exporter,node_github toneMint
class node_manager,node_switching toneRose
class node_target toneIndigo
```

## Components

### App Interface

- [Menu Bar](https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/macOS/ModernKey/AppDelegate.m): `Source/Sources/MacKey/macOS/ModernKey/AppDelegate.m`
- [Settings Dashboard](https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/macOS/ModernKey/ViewController.m): `Source/Sources/MacKey/macOS/ModernKey/ViewController.m`
- [Macro Manager](https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/macOS/ModernKey/MacroViewController.mm): `Source/Sources/MacKey/macOS/ModernKey/MacroViewController.mm`
- [Macro Suggestions](https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/macOS/ModernKey/MacroSuggestionController.mm): `Source/Sources/MacKey/macOS/ModernKey/MacroSuggestionController.mm`
- [Convert Window](https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/macOS/ModernKey/ConvertToolViewController.mm): `Source/Sources/MacKey/macOS/ModernKey/ConvertToolViewController.mm`
- [About and Updates](https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/macOS/ModernKey/AboutViewController.m): `Source/Sources/MacKey/macOS/ModernKey/AboutViewController.m`

### Typing Engine

- [Key Event Engine](https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/engine/Engine.cpp): `Source/Sources/MacKey/engine/Engine.cpp`
- [Vietnamese Rules](https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/engine/Vietnamese.cpp): `Source/Sources/MacKey/engine/Vietnamese.cpp`
- [Key Types and Codes](https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/engine/DataType.h): `Source/Sources/MacKey/engine/DataType.h`
- [Macro Runtime](https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/engine/Macro.cpp): `Source/Sources/MacKey/engine/Macro.cpp`

### Text Utilities

- [Conversion Engine](https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/engine/ConvertTool.cpp): `Source/Sources/MacKey/engine/ConvertTool.cpp`
- [XLSX Import](https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/macOS/ModernKey/xlsx_parser.py): `Source/Sources/MacKey/macOS/ModernKey/xlsx_parser.py`
- [XLSX Export](https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/macOS/ModernKey/xlsx_exporter.py): `Source/Sources/MacKey/macOS/ModernKey/xlsx_exporter.py`

### App Services

- [App Manager](https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/macOS/ModernKey/MacKeyManager.m): `Source/Sources/MacKey/macOS/ModernKey/MacKeyManager.m`
- [Smart Switching](https://github.com/dinhphu-0124/mackey/blob/main/Source/Sources/MacKey/engine/SmartSwitchKey.cpp): `Source/Sources/MacKey/engine/SmartSwitchKey.cpp`

### Other components

- **User**
- **Text Application**
- **GitHub Releases API**

## Connections

- User → Menu Bar: opens controls (evidence: `README.md`)
- User → Text Application: types text (evidence: `README.md`)
- Menu Bar → Settings Dashboard: opens settings (evidence: `README.md`)
- Menu Bar → Macro Manager: opens manager (evidence: `README.md`)
- Menu Bar → Convert Window: opens converter (evidence: `README.md`)
- Menu Bar → About and Updates: opens about (evidence: `README.md`)
- About and Updates → GitHub Releases API: checks releases (evidence: `README.md`)
- Text Application → Key Event Engine: sends keystrokes
- Key Event Engine → Text Application: replaces text
- Key Event Engine → Vietnamese Rules: uses rules
- Key Event Engine → Key Types and Codes: uses definitions
- Key Event Engine → Macro Runtime: checks suggestions
- Macro Suggestions → Macro Runtime: shows suggestions
- Settings Dashboard → Smart Switching: configures switching
- Convert Window → Conversion Engine: requests conversion
- Macro Manager → XLSX Import: imports macros (evidence: `README.md`)
- Macro Manager → XLSX Export: exports macros (evidence: `README.md`)
- App Manager → Key Event Engine: manages engine
