# xland/horsejs architecture

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

- Interactive diagram: https://gitdiagram.com/xland/horsejs
- Repository: https://github.com/xland/horsejs

## Overview

##### Project type and purpose
- This is a native desktop-application framework (HorseJs) written in C++/Win32 that hosts a WebView2 control and exposes a global JavaScript object (`horse`) to the embedded HTML/JS/CSS UI.
- Purpose: let developers write cross-platform-style desktop UIs purely in web technologies, with access to native OS features (clipboard, dialogs, file system, processes, tray, etc.) via built-in modules or user-supplied DLL plugins.

##### File structure
- Top-level:
- App/         → C++ host application (WebView2 initialization, binding JS↔C++).
- Processor/   → Native implementations of each horse.* module (Clipboard, Dialog, Fs, Net, Notify, Os, Process, Screen, Tray, Win).
- Lib/         → Third-party libraries (rapidjson) and precompiled headers.
- Script/      → Frontend JS/TS library that runs in the renderer—defines the TypeScript interfaces for horse.*, example pages, assets (css, index.html).
- Res/         → Native resources (.rc).
- TestDll/     → Sample native plugin showing how to extend with user DLL.
- main.cpp     → Entry point that ties App/ and Processor/.
- Doc/         → Markdown documentation for each module and quick-start.
- Configuration and build:
- HorseJs.sln / .vcxproj → Visual Studio solution/project.
- Script/tsconfig.json, config.json → TS compilation and runtime behavior.
- packages.config → external NuGet/WebView2 runtime dependency.

##### README
- Describes HorseJs as “using HTML/JS/CSS to create fast, stable desktop apps.”
- Lists all horse.* modules and links to their docs.
- Emphasizes a tiny single-exe (<1M) without extra DLLs, based on WebView2.

a. Main components
1. Native Host (C++ App)
- Subcomponents:
- WebView2 Controller
- JS►C++ Binding Layer (BrowserWindowConfig, BrowserWindowPage)
- Message Dispatcher (MsgProcessor)
- Module Manager (loads Processor/*)
- JSON Parser/Serializer (rapidjson)
2. Horse Modules (Processor/*)
- One class per feature (Clipboard, Dialog, Fs, Net, etc.)
3. Script Layer (Script/*.ts)
- TypeScript wrappers for horse.*
- UI assets (index.html + css)
4. User UI
- HTML/CSS pages, event handlers call horse APIs
5. Optional Plugin DLL (TestDll)
- Demonstrates extensibility via horse.dll module
b. Relationships & interactions
1. On startup, Native Host reads config.json → configures WebView2.
2. Host injects Script/index.html + bundled TS output into WebView.
3. UI JS calls window.chrome.webview.postMessage({module, method, args}).
4. Message Dispatcher receives JSON → routes to the correct Processor module → executes native code.
5. Processor returns result → serialized via rapidjson → posted back to JS.
6. JS promise resolves, UI updates.
7. For user-supplied feature, horse.dll module loads external DLL via Dll.cpp.
c. Architectural patterns/design principles
- Message-based RPC between renderer and host
- Adapter/facade pattern: each horse.* module is a facade over Win32 API
- Plugin architecture: DLL loading for extensibility
- Single responsibility: one Processor class per feature
- Layered separation: UI layer (HTML/JS), script library (TS), native host, modules, third-party libs
d. Key technologies/frameworks/libraries
- C++17 with Win32/WebView2
- rapidjson for JSON handling
- TypeScript for strong typing in the script layer
- HTML/CSS for UI
- Visual Studio solution/project files
- WebView2 runtime (Edge-based)

##### Final advice
- Every processor module as a separate node
- Layered nature (UI → Script API → Host → Native modules)
- Do not omit the rapidjson library and TestDll extensibility path

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers
    subgraph "UI Layer"
        UI["UI Pages (HTML/CSS)"]:::external
    end

    subgraph "Script Library"
        Script["Script Layer (TS/JS)"]:::script
    end

    subgraph "Native Host"
        Host["Native Host (C++ App)"]:::native
        Web["WebView2 Controller"]:::native
        Bind["JS↔C++ Binding Layer"]:::native
        Dispatcher["Message Dispatcher"]:::native
        Manager["Module Manager & Core Runtime"]:::native
        JSON["rapidjson (JSON Parser/Serializer)"]:::library
    end

    subgraph "Horse Modules"
        Clipboard["Clipboard"]:::native
        Dialog["Dialog"]:::native
        Fs["Fs"]:::native
        Net["Net"]:::native
        Notify["Notify"]:::native
        Os["Os"]:::native
        Process["Process"]:::native
        Screen["Screen"]:::native
        Tray["Tray"]:::native
        Win["Win"]:::native
        Res["Res"]:::native
        DllMod["Dll"]:::native
    end

    Plugin["Plugin DLL (TestDll)"]:::external

    %% Connections
    UI -->|"loads"| Script
    Script -->|"initializes"| Web
    Web -->|"injects HTML/JS"| Host
    Host -->|"binds via"| Bind
    Bind -->|"posts messages to"| Dispatcher
    Dispatcher -->|"routes to"| Manager
    Manager -->|"invokes"| Clipboard
    Manager -->|"invokes"| Dialog
    Manager -->|"invokes"| Fs
    Manager -->|"invokes"| Net
    Manager -->|"invokes"| Notify
    Manager -->|"invokes"| Os
    Manager -->|"invokes"| Process
    Manager -->|"invokes"| Screen
    Manager -->|"invokes"| Tray
    Manager -->|"invokes"| Win
    Manager -->|"invokes"| Res
    Manager -->|"invokes"| DllMod
    Clipboard -->|"uses"| JSON
    Dialog -->|"uses"| JSON
    Fs -->|"uses"| JSON
    Net -->|"uses"| JSON
    Notify -->|"uses"| JSON
    Os -->|"uses"| JSON
    Process -->|"uses"| JSON
    Screen -->|"uses"| JSON
    Tray -->|"uses"| JSON
    Win -->|"uses"| JSON
    Res -->|"uses"| JSON
    DllMod -->|"uses"| JSON
    DllMod -->|"loads"| Plugin
    JSON -->|"serializes"| Bind
    Bind -->|"responds to"| Script

    %% Click Events: UI Layer
    click UI "https://github.com/xland/horsejs/blob/main/Script/index.html"
    click UI "https://github.com/xland/horsejs/blob/main/Script/css/example.css"
    click UI "https://github.com/xland/horsejs/blob/main/Script/css/iconfont.css"
    click UI "https://github.com/xland/horsejs/blob/main/Script/example/clipboard.html"
    click UI "https://github.com/xland/horsejs/blob/main/Script/example/dialog.html"
    click UI "https://github.com/xland/horsejs/blob/main/Script/example/fs.html"
    click UI "https://github.com/xland/horsejs/blob/main/Script/example/net.html"
    click UI "https://github.com/xland/horsejs/blob/main/Script/example/notify.html"
    click UI "https://github.com/xland/horsejs/blob/main/Script/example/os.html"
    click UI "https://github.com/xland/horsejs/blob/main/Script/example/process.html"
    click UI "https://github.com/xland/horsejs/blob/main/Script/example/screen.html"
    click UI "https://github.com/xland/horsejs/blob/main/Script/example/tray.html"
    click UI "https://github.com/xland/horsejs/blob/main/Script/example/window.html"

    %% Click Events: Script Library
    click Script "https://github.com/xland/horsejs/blob/main/Script/Horse.ts"
    click Script "https://github.com/xland/horsejs/blob/main/Script/Types.ts"
    click Script "https://github.com/xland/horsejs/blob/main/Script/Util.ts"
    click Script "https://github.com/xland/horsejs/blob/main/Script/Eventer.ts"
    click Script "https://github.com/xland/horsejs/blob/main/Script/Clipboard.ts"
    click Script "https://github.com/xland/horsejs/blob/main/Script/Dialog.ts"
    click Script "https://github.com/xland/horsejs/blob/main/Script/Fs.ts"
    click Script "https://github.com/xland/horsejs/blob/main/Script/Net.ts"
    click Script "https://github.com/xland/horsejs/blob/main/Script/Notify.ts"
    click Script "https://github.com/xland/horsejs/blob/main/Script/Os.ts"
    click Script "https://github.com/xland/horsejs/blob/main/Script/Process.ts"
    click Script "https://github.com/xland/horsejs/blob/main/Script/Screen.ts"
    click Script "https://github.com/xland/horsejs/blob/main/Script/Tray.ts"
    click Script "https://github.com/xland/horsejs/blob/main/Script/Win.ts"
    click Script "https://github.com/xland/horsejs/blob/main/Script/Res.ts"
    click Script "https://github.com/xland/horsejs/blob/main/Script/Dll.ts"
    click Script "https://github.com/xland/horsejs/blob/main/Script/WebView2.d.ts"
    click Script "https://github.com/xland/horsejs/blob/main/Script/config.json"
    click Script "https://github.com/xland/horsejs/blob/main/Script/tsconfig.json"

    %% Click Events: Native Host
    click Host "https://github.com/xland/horsejs/blob/main/main.cpp"
    click Host "https://github.com/xland/horsejs/blob/main/App/App.cpp"
    click Host "https://github.com/xland/horsejs/blob/main/App/App.h"
    click Web "https://github.com/xland/horsejs/blob/main/App/BrowserWindow.cpp"
    click Web "https://github.com/xland/horsejs/blob/main/App/BrowserWindow.h"
    click Web "https://github.com/xland/horsejs/blob/main/App/BrowserWindowConfig.cpp"
    click Web "https://github.com/xland/horsejs/blob/main/App/BrowserWindowPage.cpp"
    click Bind "https://github.com/xland/horsejs/blob/main/App/JsonParsor.cpp"
    click Bind "https://github.com/xland/horsejs/blob/main/App/JsonParsor.h"
    click Bind "https://github.com/xland/horsejs/blob/main/App/Util.cpp"
    click Bind "https://github.com/xland/horsejs/blob/main/App/Util.h"
    click Dispatcher "https://github.com/xland/horsejs/blob/main/Processor/MsgProcessor.cpp"
    click Dispatcher "https://github.com/xland/horsejs/blob/main/Processor/MsgProcessor.h"
    click Manager "https://github.com/xland/horsejs/blob/main/Processor/Horse.cpp"
    click Manager "https://github.com/xland/horsejs/blob/main/Processor/Horse.h"

    %% Click Events: JSON
    click JSON "https://github.com/xland/horsejs/tree/main/Lib/rapidjson/"

    %% Click Events: Horse Modules
    click Clipboard "https://github.com/xland/horsejs/blob/main/Processor/Clipboard.cpp"
    click Clipboard "https://github.com/xland/horsejs/blob/main/Processor/Clipboard.h"
    click Dialog "https://github.com/xland/horsejs/blob/main/Processor/Dialog.cpp"
    click Dialog "https://github.com/xland/horsejs/blob/main/Processor/Dialog.h"
    click Fs "https://github.com/xland/horsejs/blob/main/Processor/Fs.cpp"
    click Fs "https://github.com/xland/horsejs/blob/main/Processor/Fs.h"
    click Net "https://github.com/xland/horsejs/blob/main/Processor/Net.cpp"
    click Net "https://github.com/xland/horsejs/blob/main/Processor/Net.h"
    click Notify "https://github.com/xland/horsejs/blob/main/Processor/Notify.cpp"
    click Notify "https://github.com/xland/horsejs/blob/main/Processor/Notify.h"
    click Os "https://github.com/xland/horsejs/blob/main/Processor/Os.cpp"
    click Os "https://github.com/xland/horsejs/blob/main/Processor/Os.h"
    click Process "https://github.com/xland/horsejs/blob/main/Processor/Process.cpp"
    click Process "https://github.com/xland/horsejs/blob/main/Processor/Process.h"
    click Screen "https://github.com/xland/horsejs/blob/main/Processor/Screen.cpp"
    click Screen "https://github.com/xland/horsejs/blob/main/Processor/Screen.h"
    click Tray "https://github.com/xland/horsejs/blob/main/Processor/Tray.cpp"
    click Tray "https://github.com/xland/horsejs/blob/main/Processor/Tray.h"
    click Win "https://github.com/xland/horsejs/blob/main/Processor/Win.cpp"
    click Win "https://github.com/xland/horsejs/blob/main/Processor/Win.h"
    click Res "https://github.com/xland/horsejs/blob/main/Processor/Res.cpp"
    click Res "https://github.com/xland/horsejs/blob/main/Processor/Res.h"
    click DllMod "https://github.com/xland/horsejs/blob/main/Processor/Dll.cpp"
    click DllMod "https://github.com/xland/horsejs/blob/main/Processor/Dll.h"

    %% Click Events: Plugin
    click Plugin "https://github.com/xland/horsejs/blob/main/TestDll/TestClass.cpp"
    click Plugin "https://github.com/xland/horsejs/blob/main/TestDll/TestClass.h"
    click Plugin "https://github.com/xland/horsejs/blob/main/TestDll/dllmain.cpp"
    click Plugin "https://github.com/xland/horsejs/blob/main/TestDll/pch.cpp"
    click Plugin "https://github.com/xland/horsejs/blob/main/TestDll/pch.h"
    click Plugin "https://github.com/xland/horsejs/blob/main/TestDll/framework.h"

    %% Styles
    classDef native fill:#f9f,stroke:#333,stroke-width:1px
    classDef script fill:#9ff,stroke:#333,stroke-width:1px
    classDef external fill:#ff9,stroke:#333,stroke-width:1px
    classDef library fill:#cfc,stroke:#333,stroke-width:1px
```
