# dongyuwei/hallelujah-windows architecture

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

- Interactive diagram: https://gitdiagram.com/dongyuwei/hallelujah-windows
- Repository: https://github.com/dongyuwei/hallelujah-windows

## Overview

1. **What this repo is**
   - This is a Windows input-method platform built on PIME/TSF, with the Hallelujah English IME ported on top.
   - The architecture is split into a native Windows text-service layer, a launcher/IPC layer, and language-engine backends implemented in Python and Node.js.

2. **Windows integration boundary**
   - `PIMETextService/` is the TSF COM DLL that Windows loads as the actual text service.
   - It contains the IME module, language bar button, and the client-side bridge that talks to backend processes.
   - This is the boundary where raw keyboard events enter the system and composition/candidate text is sent back to the OS.

3. **Native lifecycle and process supervision**
   - `PIMELauncher/` is the always-on helper process mentioned in the README as the startup daemon.
   - It appears to manage backend processes and secure IPC channels using named pipes.
   - Key pieces are `PipeServer`, `PipeClient`, `PipeSecurity`, `BackendServer`, and `UvPipe`, which together suggest process orchestration plus authenticated pipe-based communication.

4. **IPC and control plane**
   - The native text service does not do the heavy language work itself.
   - It forwards requests to backend workers over named pipes, and receives candidate lists, commit text, and state updates back.
   - `backends.json` likely acts as the registry of available backend services or input methods.

5. **Python backend runtime**
   - The `python/` tree is the main backend runtime for many input methods.
   - `python/server.py`, `python/serviceManager.py`, and `python/textService.py` look like the process entrypoint, process/service manager, and TSF-facing service logic on the Python side.
   - The bundled `python/python3/` directory indicates the project ships its own embedded Python runtime and dependencies.

6. **Node.js backend runtime**
   - The `node/` tree is a second backend runtime for JavaScript-based input methods.
   - `node/server.js` and `node/loadServices.js` are the runtime entrypoints/loader, with per-IME packages under `node/input_methods/`.
   - This gives the platform a second plugin ecosystem alongside Python.

7. **Input-method plugin model**
   - Each input method is packaged as its own folder with an `ime.json` manifest and backend implementation.
   - Examples include `python/input_methods/chewing`, `python/input_methods/rime`, `python/input_methods/hallelujah`, and `node/input_methods/emojime`.
   - The manifests define how the backend is discovered, loaded, and surfaced to the launcher/text service.

8. **Hallelujah English IME data path**
   - The Hallelujah-specific backend is centered in `python/input_methods/hallelujah/ime_hallelujah.py`.
   - Its data comes from a local dictionary/translation store under `python/input_methods/hallelujah/dict/`, including word frequency, fuzzy phonetics, translations, and CEDICT-derived resources.
   - User-defined expansions are supported via a user-level JSON file as described in the README, making personalization part of the backend data flow.

9. **Shared linguistic engines and dictionaries**
   - The repo carries multiple reusable language resources under `python/cinbase`, `python/libchewing`, `python/opencc`, and `python/input_methods/rime/data`.
   - These provide candidate generation, conversion, phonetic matching, and Chinese/English support for different IMEs.
   - The architecture is data-heavy: most IME behavior is driven by bundled tables, JSON, SQLite, and `.cin`/`.dat` dictionaries rather than hardcoded logic.

10. **Configuration and user-facing tools**
   - Several input methods expose local configuration UIs via HTML/JS assets under their own folders, such as `config/`, `js/`, and `user_phrase_editor.html`.
   - `python/cinbase/configtool.py` and the chewing-specific config tools show that backend services also generate or serve config views.
   - This UI layer is separate from the TSF runtime and is used for editing layouts, phrases, and IME options.

11. **Packaging and installation**
   - `installer/` contains the NSIS-based packaging system, plus third-party installer plugins.
   - The final deployed shape described in the README is: `PIMETextService.dll`, `python/`, and `node/` installed under `C:\Program Files (x86)\PIME\`.
   - Registration of the COM DLL via `regsvr32` is required, which confirms the Windows shell/TSF integration boundary.

12. **Build and CI boundary**
   - The native components are built with CMake and Visual Studio, while Python/Node runtimes and their dependencies are vendored into the repo.
   - GitHub Actions, AppVeyor, and local batch scripts support Windows CI and release packaging.
   - The architecture diagram should therefore show three deployable strata: native TSF service, launcher/IPC supervisor, and pluggable language backends with bundled data and config assets.

Main entry points: [`PIMETextService`](https://github.com/dongyuwei/hallelujah-windows/tree/master/PIMETextService) (Text Service), [`python/textService.py`](https://github.com/dongyuwei/hallelujah-windows/blob/master/python/textService.py) (Python Service), [`installer`](https://github.com/dongyuwei/hallelujah-windows/tree/master/installer) (Installer), [`PIMELauncher/BackendServer.cpp`](https://github.com/dongyuwei/hallelujah-windows/blob/master/PIMELauncher/BackendServer.cpp) (Backend Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_native["Native Windows"]
  node_pime_text_service["Text Service<br/>TSF COM DLL"]
  node_pime_client["Client Bridge<br/>TSF bridge<br/>[PIMEClient.cpp]"]
  node_ime_module["IME Module<br/>TSF module<br/>[PIMEImeModule.cpp]"]
  node_lang_bar["Lang Bar<br/>UI hook"]
  node_launcher["Launcher<br/>native supervisor<br/>[PIMELauncher.cpp]"]
  node_pipe_server["Pipe Server<br/>[PipeServer.cpp]"]
  node_pipe_client["Pipe Client<br/>[PipeClient.cpp]"]
  node_backend_server["Backend Server<br/>process manager<br/>[BackendServer.cpp]"]
end

subgraph group_runtime["Backend runtimes"]
  node_python_server["Python Host<br/>backend runtime<br/>[server.py]"]
  node_python_manager["Service Manager<br/>python supervisor<br/>[serviceManager.py]"]
  node_python_text_service["Python Service<br/>IME service<br/>[textService.py]"]
  node_node_server["Node Host<br/>backend runtime<br/>[server.js]"]
  node_node_loader["Service Loader<br/>plugin loader<br/>[loadServices.js]"]
  node_hallelujah["Hallelujah IME<br/>english IME<br/>[ime_hallelujah.py]"]
  node_chewing["Chewing IME<br/>phonetic IME<br/>[chewing_ime.py]"]
  node_rime["Rime IME<br/>rime bridge<br/>[rime_ime.py]"]
  node_emojime["Emoji IME<br/>node plugin"]
end

subgraph group_data["Language data"]
  node_backends_json["Backend Registry<br/>manifest registry<br/>[backends.json]"]
  node_hallelujah_dict[("Hallelujah Data<br/>dicts + sqlite")]
  node_cinbase["Cin Base<br/>symbol tables"]
  node_libchewing[("Chewing Data<br/>chewing tables")]
  node_opencc[("OpenCC<br/>conversion data")]
end

subgraph group_packaging["Build & release"]
  node_installer["Installer<br/>nsis packaging"]
  node_ci["CI & Build<br/>build automation<br/>[ci.yaml]"]
end

node_launcher -->|"hosts"| node_pipe_server
node_launcher -->|"starts"| node_backend_server
node_pipe_server -->|"connects"| node_pipe_client
node_pime_text_service -->|"uses"| node_pime_client
node_pime_text_service -->|"implements"| node_ime_module
node_pime_text_service -->|"exposes"| node_lang_bar
node_pime_client -->|"IPC"| node_pipe_client
node_backend_server -->|"spawns"| node_python_server
node_backend_server -->|"spawns"| node_node_server
node_python_server -->|"manages"| node_python_manager
node_python_manager -->|"routes"| node_python_text_service
node_node_server -->|"loads"| node_node_loader
node_python_text_service -->|"serves"| node_hallelujah
node_python_text_service -->|"serves"| node_chewing
node_python_text_service -->|"serves"| node_rime
node_node_loader -->|"loads"| node_emojime
node_backends_json -->|"registers"| node_backend_server
node_hallelujah -->|"reads"| node_hallelujah_dict
node_chewing -->|"shares"| node_cinbase
node_rime -->|"converts"| node_opencc
node_installer -->|"packages"| node_pime_text_service
node_installer -->|"packages"| node_python_server
node_installer -->|"packages"| node_node_server
node_ci -->|"builds"| node_installer
node_ci -->|"builds"| node_pime_text_service

click node_pime_text_service "https://github.com/dongyuwei/hallelujah-windows/tree/master/PIMETextService"
click node_pime_client "https://github.com/dongyuwei/hallelujah-windows/blob/master/PIMETextService/PIMEClient.cpp"
click node_ime_module "https://github.com/dongyuwei/hallelujah-windows/blob/master/PIMETextService/PIMEImeModule.cpp"
click node_lang_bar "https://github.com/dongyuwei/hallelujah-windows/blob/master/PIMETextService/PIMELangBarButton.cpp"
click node_launcher "https://github.com/dongyuwei/hallelujah-windows/blob/master/PIMELauncher/PIMELauncher.cpp"
click node_pipe_server "https://github.com/dongyuwei/hallelujah-windows/blob/master/PIMELauncher/PipeServer.cpp"
click node_pipe_client "https://github.com/dongyuwei/hallelujah-windows/blob/master/PIMELauncher/PipeClient.cpp"
click node_backend_server "https://github.com/dongyuwei/hallelujah-windows/blob/master/PIMELauncher/BackendServer.cpp"
click node_python_server "https://github.com/dongyuwei/hallelujah-windows/blob/master/python/server.py"
click node_python_manager "https://github.com/dongyuwei/hallelujah-windows/blob/master/python/serviceManager.py"
click node_python_text_service "https://github.com/dongyuwei/hallelujah-windows/blob/master/python/textService.py"
click node_node_server "https://github.com/dongyuwei/hallelujah-windows/blob/master/node/server.js"
click node_node_loader "https://github.com/dongyuwei/hallelujah-windows/blob/master/node/loadServices.js"
click node_hallelujah "https://github.com/dongyuwei/hallelujah-windows/blob/master/python/input_methods/hallelujah/ime_hallelujah.py"
click node_chewing "https://github.com/dongyuwei/hallelujah-windows/blob/master/python/input_methods/chewing/chewing_ime.py"
click node_rime "https://github.com/dongyuwei/hallelujah-windows/blob/master/python/input_methods/rime/rime_ime.py"
click node_emojime "https://github.com/dongyuwei/hallelujah-windows/tree/master/node/input_methods/emojime"
click node_backends_json "https://github.com/dongyuwei/hallelujah-windows/blob/master/backends.json"
click node_hallelujah_dict "https://github.com/dongyuwei/hallelujah-windows/tree/master/python/input_methods/hallelujah/dict"
click node_cinbase "https://github.com/dongyuwei/hallelujah-windows/tree/master/python/cinbase"
click node_libchewing "https://github.com/dongyuwei/hallelujah-windows/tree/master/python/libchewing"
click node_opencc "https://github.com/dongyuwei/hallelujah-windows/tree/master/python/opencc"
click node_installer "https://github.com/dongyuwei/hallelujah-windows/tree/master/installer"
click node_ci "https://github.com/dongyuwei/hallelujah-windows/blob/master/.github/workflows/ci.yaml"

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_pime_text_service,node_pime_client,node_ime_module,node_lang_bar,node_launcher,node_pipe_server,node_pipe_client,node_backend_server toneBlue
class node_python_server,node_python_manager,node_python_text_service,node_node_server,node_node_loader,node_hallelujah,node_chewing,node_rime,node_emojime toneAmber
class node_backends_json,node_hallelujah_dict,node_cinbase,node_libchewing,node_opencc toneMint
class node_installer,node_ci toneRose
```

## Components

### Native Windows

TSF COM text service and launcher/supervisor boundary.

- [Text Service](https://github.com/dongyuwei/hallelujah-windows/tree/master/PIMETextService): TSF COM DLL · Windows-loaded text service boundary that handles keyboard input and composition output. · `PIMETextService`
- [Client Bridge](https://github.com/dongyuwei/hallelujah-windows/blob/master/PIMETextService/PIMEClient.cpp): TSF bridge · Client-side adapter inside the text service that forwards requests to backend processes. · `PIMETextService/PIMEClient.cpp`
- [IME Module](https://github.com/dongyuwei/hallelujah-windows/blob/master/PIMETextService/PIMEImeModule.cpp): TSF module · IME lifecycle and Windows text service integration logic. · `PIMETextService/PIMEImeModule.cpp`
- [Lang Bar](https://github.com/dongyuwei/hallelujah-windows/blob/master/PIMETextService/PIMELangBarButton.cpp): UI hook · Language bar button and status UI exposed to Windows. · `PIMETextService/PIMELangBarButton.cpp`
- [Launcher](https://github.com/dongyuwei/hallelujah-windows/blob/master/PIMELauncher/PIMELauncher.cpp): native supervisor · Always-on helper process that starts and supervises backend workers. · `PIMELauncher/PIMELauncher.cpp`
- [Pipe Server](https://github.com/dongyuwei/hallelujah-windows/blob/master/PIMELauncher/PipeServer.cpp): named-pipe server · Authenticated pipe listener for backend/control-plane traffic. · `PIMELauncher/PipeServer.cpp`
- [Pipe Client](https://github.com/dongyuwei/hallelujah-windows/blob/master/PIMELauncher/PipeClient.cpp): named-pipe client · Client endpoint used by the supervisor to connect to backend services. · `PIMELauncher/PipeClient.cpp`
- [Backend Server](https://github.com/dongyuwei/hallelujah-windows/blob/master/PIMELauncher/BackendServer.cpp): process manager · Launches and tracks backend service processes and their IPC endpoints. · `PIMELauncher/BackendServer.cpp`

### Backend runtimes

Python and Node.js service hosts plus bundled language plugins.

- [Python Host](https://github.com/dongyuwei/hallelujah-windows/blob/master/python/server.py): backend runtime · Python service entrypoint for IME backends. · `python/server.py`
- [Service Manager](https://github.com/dongyuwei/hallelujah-windows/blob/master/python/serviceManager.py): python supervisor · Python-side process/service coordination and backend registration. · `python/serviceManager.py`
- [Python Service](https://github.com/dongyuwei/hallelujah-windows/blob/master/python/textService.py): IME service · Python-side TSF-facing runtime logic and request handling. · `python/textService.py`
- [Node Host](https://github.com/dongyuwei/hallelujah-windows/blob/master/node/server.js): backend runtime · Node.js service entrypoint for JavaScript-based input methods. · `node/server.js`
- [Service Loader](https://github.com/dongyuwei/hallelujah-windows/blob/master/node/loadServices.js): plugin loader · Discovers and loads Node input-method packages. · `node/loadServices.js`
- [Hallelujah IME](https://github.com/dongyuwei/hallelujah-windows/blob/master/python/input_methods/hallelujah/ime_hallelujah.py): english IME · Hallelujah-specific backend implementing the English input method. · `python/input_methods/hallelujah/ime_hallelujah.py`
- [Chewing IME](https://github.com/dongyuwei/hallelujah-windows/blob/master/python/input_methods/chewing/chewing_ime.py): phonetic IME · Chewing-related backend and config flow used as a major Python IME subsystem. · `python/input_methods/chewing/chewing_ime.py`
- [Rime IME](https://github.com/dongyuwei/hallelujah-windows/blob/master/python/input_methods/rime/rime_ime.py): rime bridge · Rime-backed input method integration and key-event handling. · `python/input_methods/rime/rime_ime.py`
- [Emoji IME](https://github.com/dongyuwei/hallelujah-windows/tree/master/node/input_methods/emojime): node plugin · Node-based plugin example providing emoji input behavior. · `node/input_methods/emojime`

### Language data

Shared dictionaries, conversion tables, and manifests used by IMEs.

- [Backend Registry](https://github.com/dongyuwei/hallelujah-windows/blob/master/backends.json): manifest registry · Registry of available backend services and input methods. · `backends.json`
- [Hallelujah Data](https://github.com/dongyuwei/hallelujah-windows/tree/master/python/input_methods/hallelujah/dict): dicts + sqlite · Dictionary, frequency, translation, and phonetic resources for the Hallelujah backend. · `python/input_methods/hallelujah/dict`
- [Cin Base](https://github.com/dongyuwei/hallelujah-windows/tree/master/python/cinbase): symbol tables · Shared `.cin`/JSON dictionary base and config tooling for multiple phonetic IMEs. · `python/cinbase`
- [Chewing Data](https://github.com/dongyuwei/hallelujah-windows/tree/master/python/libchewing): chewing tables · Libchewing dictionaries and phonetic support data. · `python/libchewing`
- [OpenCC](https://github.com/dongyuwei/hallelujah-windows/tree/master/python/opencc): conversion data · OpenCC conversion mappings and character/phrase tables. · `python/opencc`

### Build & release

Build scripts, installer, and CI/release automation.

- [Installer](https://github.com/dongyuwei/hallelujah-windows/tree/master/installer): nsis packaging · NSIS installer, plugins, and deployment scripts for Windows release packaging. · `installer`
- [CI & Build](https://github.com/dongyuwei/hallelujah-windows/blob/master/.github/workflows/ci.yaml): build automation · CMake, batch scripts, and GitHub/AppVeyor workflows used to build and release the platform. · `.github/workflows/ci.yaml`

## Connections

- Launcher → Pipe Server: hosts · Launcher exposes the control channel for backend supervision.
- Launcher → Backend Server: starts · Launcher starts and manages backend worker processes.
- Pipe Server → Pipe Client: connects · Named-pipe endpoints exchange control messages and service calls.
- Text Service → Client Bridge: uses · Text service delegates backend communication to the client bridge.
- Text Service → IME Module: implements · IME module contains the TSF-facing text-service behavior.
- Text Service → Lang Bar: exposes · Windows language bar integration is part of the native UI boundary.
- Client Bridge → Pipe Client: IPC · Client bridge sends requests over named pipes.
- Backend Server → Python Host: spawns · Supervisor launches Python backend host processes.
- Backend Server → Node Host: spawns · Supervisor launches Node backend host processes.
- Python Host → Service Manager: manages · Python host delegates lifecycle and service orchestration.
- Service Manager → Python Service: routes · Python-side service layer handles IME requests and responses.
- Node Host → Service Loader: loads · Node host discovers and loads plugin packages.
- Python Service → Hallelujah IME: serves · Python service hosts the Hallelujah IME backend.
- Python Service → Chewing IME: serves · Python service hosts the Chewing backend.
- Python Service → Rime IME: serves · Python service hosts the Rime backend.
- Service Loader → Emoji IME: loads · Node runtime loads per-IME packages such as Emojime.
- Backend Registry → Backend Server: registers · Backend registry informs the launcher which services exist.
- Hallelujah IME → Hallelujah Data: reads · Hallelujah backend depends on local dictionary and frequency data.
- Chewing IME → Cin Base: shares · Chewing and related IMEs reuse common symbol and config resources.
- Rime IME → OpenCC: converts · Rime integration uses OpenCC conversion tables and mappings.
- Installer → Text Service: packages · Installer bundles the TSF DLL for Windows deployment.
- Installer → Python Host: packages · Installer bundles Python runtime and backend assets.
- Installer → Node Host: packages · Installer bundles Node runtime and backend assets.
- CI & Build → Installer: builds · CI and build scripts produce release installers.
- CI & Build → Text Service: builds · Native build pipeline compiles the TSF components.
