# nervjs/taro-harmony-capi-library architecture

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

- Interactive diagram: https://gitdiagram.com/nervjs/taro-harmony-capi-library
- Repository: https://github.com/nervjs/taro-harmony-capi-library

## Overview

##### Project Type and Purpose
- The project is a C++ library intended for building a UI and runtime engine. It integrates JavaScript execution (via JSI executors and QuickJS implementations), DOM management, CSS styling (cssom), animation, event handling, and native module exports.
- The library seems to focus on bridging JavaScript with native C++ operations (as seen in directories like arkjs and engine) and offers extensive runtime modules (in the runtime directory) that manage DOM nodes, stylesheets, and event handling.

##### File Structure – Identify Main Modules
- arkjs: Contains core files (ArkJS.cpp/h, ArkTSBridge.cpp/h, Scope.h). This module likely handles JavaScript integration and provides the interface for bridging types and executing JS code from C++.
- engine: This module is split into several parts:
– jsi_executor: Implements JavaScript invocation/execution functions. It includes native module support and factories for QuickJS executors.
– quickjs_jsi and react_common: Provide runtime support using the QuickJS engine and React integration patterns (invoking methods, managing module registries, handling callbacks).
- exports: Likely exposes public APIs for document/model management, event handling, and framework integration (notably for React and NAPI bridges).
- runtime: This is the largest module and includes subdirectories for:
– API: Specific node APIs.
– cssom: CSS Object Model – handling stylesheets, parsers, dimensions, fonts, and their parameters.
– dom: Manages everything from node definitions, element rendering, animations, events (including complex gesture, touch, and user events) to event factories.
– Other runtime functionalities such as vsync, resource management, and rendering.
- helper: Contains various utility functions and classes (e.g., file management, logging, timer, string/array utilities) that underpin different modules.
- system and taro: Provide system and instance management functionalities, as well as native logging and possibly platform-specific adjustments.
- thread: Manages task runners, executors, and threading functionality ensuring asynchronous and concurrent task handling.
- patches: Contains configuration adjustments and patches for third-party libraries (e.g., folly, libevent) to support the cross-platform or embedded requirements.
- types: Contains TypeScript definition files and scripts; likely to aid in integration with TypeScript/JS frameworks or serve as API contracts.

##### Components Impacting the Architecture
- JavaScript Integration: arkjs and engine modules manage JavaScript execution, bridging the gap between native C++ and JS runtime (using JSI executors and factories).
- Rendering and DOM: The runtime directory’s extensive sub-modules (dom, cssom, animation, event) represent the system’s rendering engine and dynamic UI behavior.
- API and Exports: The exports folder, along with taro and runtime/api, exposes interfaces for developers to interact with the library.
- Concurrency: The thread module indicates a design that employs multi-threading and asynchronous task handling.
- External Integration: Files like commitlint.config.js, CMakeLists.txt, patches for external libraries, and GitHub workflows hint at continuous integration and automated build processes.

##### Relationships and Interactions
- The engine module interacts with arkjs and the runtime to provide a smooth JavaScript execution environment that supports the UI system.
- The runtime’s DOM, CSSOM, and event components work in tandem to construct a dynamic user interface driven by the underlying engine.
- Helper utilities are used across modules to provide cross-cutting concerns such as logging, file operations, and performance metrics.
- The exports layer serves as the interface between the library’s core functionality and clients (for native module integration or exposing APIs to higher-level applications).
- The test directory (and CI configurations under .github/workflows) ensures architectural reliability and proper functioning of these interactions.

##### Important Architectural Patterns
- Modularity: The project is clearly divided into modules by functionality (engine, runtime, helper, etc.), which aids in separation of concerns.
- Layered Architecture: Lower-level utilities and patches support the mid-level execution (JSI engines and helper libraries) and high-level runtime features (DOM, CSSOM, events).
- Plugin/Bridge Patterns: The presence of bridge files (e.g., ArkTSBridge) and multiple executor factories point towards an extensible design that can integrate with different JavaScript runtimes.
- Event-Driven and Asynchronous Processing: The threading and event modules emphasize asynchronous data flows, common in UI frameworks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% JavaScript Integration Layer
    subgraph "JavaScript Integration"
        A["ArkJS (JS Bridge)"]:::jsIntegration
    end

    %% Engine Module Layer
    subgraph "Engine Module"
        E1["JSI Executor"]:::engine
        E2["QuickJS Support"]:::engine
        E3["React Common Executor"]:::engine
    end

    %% Runtime Module Layer
    subgraph "Runtime Module"
        R["Runtime (DOM, CSSOM, Animation, Events)"]:::runtime
    end

    %% Exports/API Module Layer
    subgraph "Exports/API Module"
        X["Exports/API"]:::exports
    end

    %% System Module Layer
    subgraph "System Module"
        S["System Info"]:::system
        Ta["Taro Instance"]:::system
    end

    %% Threading Module Layer
    subgraph "Threading Module"
        T["Threading / Task Execution"]:::thread
    end

    %% Helper Utilities Layer
    subgraph "Helper Utilities"
        H["Helper Utilities"]:::helper
    end

    %% Build & Patches Layer
    subgraph "Build & Patches"
        B["Build & Patches"]:::build
    end

    %% TypeScript Definitions Layer
    subgraph "TypeScript Definitions"
        TS["TypeScript Definitions"]:::ts
    end

    %% Connections between layers
    A -->|"calls"| E1
    E1 -->|"uses"| E2
    E1 -->|"integrates"| E3
    E1 -->|"updates"| R
    E2 -->|"updates"| R
    E3 -->|"updates"| R
    R -->|"exposes"| X

    T -->|"executes"| E1
    T -->|"executes"| R

    H -->|"supports"| A
    H -->|"supports"| E1
    H -->|"supports"| R
    H -->|"supports"| X

    R -->|"logsTo"| S
    R -->|"instancesIn"| Ta

    B -->|"buildConfig"| A
    B -->|"buildConfig"| E1
    B -->|"buildConfig"| R
    B -->|"buildConfig"| X

    TS -->|"contracts"| X

    %% Class styles
    classDef jsIntegration fill:#FFC0CB,stroke:#000,stroke-width:2px
    classDef engine fill:#ADD8E6,stroke:#000,stroke-width:2px
    classDef runtime fill:#90EE90,stroke:#000,stroke-width:2px
    classDef exports fill:#FFFF99,stroke:#000,stroke-width:2px
    classDef system fill:#D3D3D3,stroke:#000,stroke-width:2px
    classDef thread fill:#FFA07A,stroke:#000,stroke-width:2px
    classDef helper fill:#FFB6C1,stroke:#000,stroke-width:2px
    classDef build fill:#E6E6FA,stroke:#000,stroke-width:2px
    classDef ts fill:#F5DEB3,stroke:#000,stroke-width:2px

    %% Click Events
    click A "https://github.com/nervjs/taro-harmony-capi-library/tree/main/arkjs"
    click E1 "https://github.com/nervjs/taro-harmony-capi-library/tree/main/engine/jsi_executor"
    click E2 "https://github.com/nervjs/taro-harmony-capi-library/tree/main/engine/quickjs_jsi"
    click E3 "https://github.com/nervjs/taro-harmony-capi-library/tree/main/engine/react_common"
    click R "https://github.com/nervjs/taro-harmony-capi-library/tree/main/runtime"
    click X "https://github.com/nervjs/taro-harmony-capi-library/tree/main/exports"
    click H "https://github.com/nervjs/taro-harmony-capi-library/tree/main/helper"
    click T "https://github.com/nervjs/taro-harmony-capi-library/tree/main/thread"
    click S "https://github.com/nervjs/taro-harmony-capi-library/tree/main/system/system_info.cpp/h"
    click Ta "https://github.com/nervjs/taro-harmony-capi-library/tree/main/taro"
    click B "https://github.com/nervjs/taro-harmony-capi-library/blob/main/CMakeLists.txt"
    click TS "https://github.com/nervjs/taro-harmony-capi-library/tree/main/types"
```
