# openvanilla/mcbopomofo architecture

> Architecture diagram of the GitHub repository openvanilla/mcbopomofo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openvanilla/mcbopomofo
- Repository: https://github.com/openvanilla/mcbopomofo

## Overview

##### Main components
- Xcode Project & Build System:
– McBopomofo.xcodeproj defines the overall project configuration.
– GitHub workflows and scripts provide CI/CD and formatting checks.
- Installer Module:
– Located in Source/Installer.
– Handles installation logic, process kill/restart of the input method, and UI for installation (including NotarizedArchives and localized resources).
- Core Input Method Application:
– Found in Source/ (files like AppDelegate.swift, InputMethodController.swift, Preferences.swift, etc.).
– Implements the main input method functionality, UI interactions (menu, notifications, preferences), and bridges to the engine.
- Engine / Language Model & Processing Library:
– Located in Source/Engine.
– Contains C++ implementations (including language models, phrase databases, and various tests) that support on-the-fly input processing.
– May employ different modules (e.g., AssociatedPhrasesV2, McBopomofoLM, ParselessLM, and more) to handle parsing, predictions, and text transformations.
- Data and Dictionary Resources:
– Source/Data holds various text files, mappings, and scripts used to generate and update language data.
– Includes Makefiles, Python scripts, and assorted data curation resources to prepare phrase dictionaries.
- Auxiliary Swift Packages:
– Located under Packages/ (e.g., BopomofoBraille, CandidateUI, ChineseNumbers, InputSourceHelper, NSStringUtils, NotifierUI, OpenCCBridge, TooltipUI).
– These provide modular, re-usable components, often focusing on UI (candidate lists, tooltip notifications) or data processing (conversions, text utilities).

##### Relationships and interactions
- The Installer component is responsible for launching and updating the input method. It is a distinct “target” in the Xcode project and communicates with the main input method process (often via system calls to kill or relaunch the process).
- The Core Input Method (in Source/) connects the macOS services (preferences, notifications) to the Engine, dispatching input events and receiving candidate suggestions.
- The Engine (in Source/Engine) acts as the processing heart; it’s called by the InputMethodController and potentially by utility modules to compute language modeling tasks and phrase predictions.
- Swift packages interact as libraries. For example, the CandidateUI package is used for displaying candidate characters or phrases, and BopomofoBraille may handle alternative input representations.
- Data files and scripts (in Source/Data) drive the updating of dictionary entries and language model data used by the Engine; these may be processed separately and then integrated via build steps.

##### Important architectural patterns and design principles
- Modularization: The use of Swift packages encapsulates distinct functionalities (UI components, conversion utilities) for reuse and easier maintenance.
- Separation of Concerns: The installer, core app logic, and language engine are clearly divided. The UI elements are abstracted behind separate packages.
- Cross-language Integration: Bridging between Swift/Objective-C and C++ code is evident in the Engine and KeyHandler components.
- Test-Driven Development: A dedicated tests directory (McBopomofoTests and test modules in each Package) shows an emphasis on testing individual components.

##### Technologies, frameworks, and libraries
- macOS Application Frameworks: Cocoa (Swift/Objective-C) for the main application and Installer.
- CMake: For building the C++ Engine components (look into the CMakeLists.txt files in the Engine directories).
- Swift Package Manager: Manages the auxiliary packages hosted in the Packages/ folder.
- Scripting Languages: Python and shell scripts for processing data (in Source/Data/bin and curation directories).
- Xcode & Build Tools: Project configuration files such as the .xcodeproj, xcshareddata, and workflow configuration files for CI.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & CI Layer
    subgraph "Build & CI"
        Xcode["Xcode Project & Build System"]:::osModule
    end

    %% Application Layer
    subgraph "Application Layer"
        Installer["Installer Module"]:::osModule
        CoreApp["Core Input Method Application"]:::osModule
        OSProcess["macOS Input Method Process"]:::osModule
    end

    %% Processing Layer
    subgraph "Processing Layer"
        Engine["Language Engine & Models (C++ with CMake)"]:::engineModule
        Data["Dictionary & Data Resources"]:::engineModule
    end

    %% Auxiliary Swift Packages Layer
    subgraph "Auxiliary Swift Packages"
        CandidateUI["CandidateUI"]:::packageModule
        BopomofoBraille["BopomofoBraille"]:::packageModule
        ChineseNumbers["ChineseNumbers"]:::packageModule
        InputSourceHelper["InputSourceHelper"]:::packageModule
        NSStringUtils["NSStringUtils"]:::packageModule
        NotifierUI["NotifierUI"]:::packageModule
        OpenCCBridge["OpenCCBridge"]:::packageModule
        TooltipUI["TooltipUI"]:::packageModule
    end

    %% Relationships from Build System to Core Components
    Xcode -->|"builds"| Installer
    Xcode -->|"builds"| CoreApp
    Xcode -->|"builds"| Engine
    Xcode -->|"packages"| CandidateUI
    Xcode -->|"packages"| BopomofoBraille
    Xcode -->|"packages"| ChineseNumbers
    Xcode -->|"packages"| InputSourceHelper
    Xcode -->|"packages"| NSStringUtils
    Xcode -->|"packages"| NotifierUI
    Xcode -->|"packages"| OpenCCBridge
    Xcode -->|"packages"| TooltipUI

    %% Application Interactions
    Installer -->|"triggers restart/kill"| OSProcess
    CoreApp -->|"dispatches input events"| Engine
    CoreApp -->|"renders UI"| CandidateUI
    CoreApp -->|"renders UI"| TooltipUI
    CoreApp -->|"notifies events"| NotifierUI

    %% Processing Interactions
    Data -->|"updates"| Engine

    %% Cross-layer Interactions
    Engine -->|"provides suggestions"| CandidateUI

    %% Class Definitions
    classDef osModule fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef engineModule fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef packageModule fill:#ffcccb,stroke:#000,stroke-width:2px;

    %% Click Events
    click Xcode "https://github.com/openvanilla/mcbopomofo/blob/master/McBopomofo.xcodeproj"
    click Installer "https://github.com/openvanilla/mcbopomofo/tree/master/Source/Installer"
    click CoreApp "https://github.com/openvanilla/mcbopomofo/tree/master/Source"
    click Engine "https://github.com/openvanilla/mcbopomofo/tree/master/Source/Engine"
    click Data "https://github.com/openvanilla/mcbopomofo/tree/master/Source/Data"
    click CandidateUI "https://github.com/openvanilla/mcbopomofo/tree/master/Packages/CandidateUI"
    click BopomofoBraille "https://github.com/openvanilla/mcbopomofo/tree/master/Packages/BopomofoBraille"
    click ChineseNumbers "https://github.com/openvanilla/mcbopomofo/tree/master/Packages/ChineseNumbers"
    click InputSourceHelper "https://github.com/openvanilla/mcbopomofo/tree/master/Packages/InputSourceHelper"
    click NSStringUtils "https://github.com/openvanilla/mcbopomofo/tree/master/Packages/NSStringUtils"
    click NotifierUI "https://github.com/openvanilla/mcbopomofo/tree/master/Packages/NotifierUI"
    click OpenCCBridge "https://github.com/openvanilla/mcbopomofo/tree/master/Packages/OpenCCBridge"
    click TooltipUI "https://github.com/openvanilla/mcbopomofo/tree/master/Packages/TooltipUI"
```
