How dongyuwei/hallelujah-windows works
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 Text Service · textService.py Python Service · installer Installer · BackendServer.cpp Backend Server
Components 24
Native Windows
TSF COM text service and launcher/supervisor boundary.
- Text Service · Windows-loaded text service boundary that handles keyboard input and composition output.
PIMETextService - Client Bridge · Client-side adapter inside the text service that forwards requests to backend processes.
PIMETextService/PIMEClient.cpp - IME Module · IME lifecycle and Windows text service integration logic.
PIMETextService/PIMEImeModule.cpp - Lang Bar · Language bar button and status UI exposed to Windows.
PIMETextService/PIMELangBarButton.cpp - Launcher · Always-on helper process that starts and supervises backend workers.
PIMELauncher/PIMELauncher.cpp - Pipe Server · Authenticated pipe listener for backend/control-plane traffic.
PIMELauncher/PipeServer.cpp - Pipe Client · Client endpoint used by the supervisor to connect to backend services.
PIMELauncher/PipeClient.cpp - Backend Server · 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 · Python service entrypoint for IME backends.
python/server.py - Service Manager · Python-side process/service coordination and backend registration.
python/serviceManager.py - Python Service · Python-side TSF-facing runtime logic and request handling.
python/textService.py - Node Host · Node.js service entrypoint for JavaScript-based input methods.
node/server.js - Service Loader · Discovers and loads Node input-method packages.
node/loadServices.js - Hallelujah IME · Hallelujah-specific backend implementing the English input method.
python/input_methods/hallelujah/ime_hallelujah.py - Chewing IME · Chewing-related backend and config flow used as a major Python IME subsystem.
python/input_methods/chewing/chewing_ime.py - Rime IME · Rime-backed input method integration and key-event handling.
python/input_methods/rime/rime_ime.py - Emoji IME · 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 · Registry of available backend services and input methods.
backends.json - Hallelujah Data · Dictionary, frequency, translation, and phonetic resources for the Hallelujah backend.
python/input_methods/hallelujah/dict - Cin Base · Shared `.cin`/JSON dictionary base and config tooling for multiple phonetic IMEs.
python/cinbase - Chewing Data · Libchewing dictionaries and phonetic support data.
python/libchewing - OpenCC · OpenCC conversion mappings and character/phrase tables.
python/opencc
Build & release
Build scripts, installer, and CI/release automation.
- Installer · NSIS installer, plugins, and deployment scripts for Windows release packaging.
installer - CI & Build · CMake, batch scripts, and GitHub/AppVeyor workflows used to build and release the platform.
.github/workflows/ci.yaml
Connections 25
- 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.