# karosli/kkjsbridge architecture

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

- Interactive diagram: https://gitdiagram.com/karosli/kkjsbridge
- Repository: https://github.com/karosli/kkjsbridge

## Overview

##### Project Type and Purpose
- This is a hybrid iOS framework (Objective-C + TypeScript) plus a demo app that bridges WKWebView and native code.
- Purpose:
- Provide a modular JSBridge implementation (message handler, module registry, synchronous/asynchronous calls).
- Hook and proxy AJAX/Fetch requests to enable offline packages, body preservation, sync requests, external proxies.
- Manage cookies between JavaScript (document.cookie) and native NSHTTPCookieStorage.
- Reuse WKWebView instances via a pool.

##### High-Level Architecture Overview
[Application Layer]
- Demo App (UIKit controllers, UIWebView wrapper)
[WebView Layer]
- KKWebView: subclass of WKWebView with extension categories (KKJSBridgeEngine attachment)
- KKWebViewPool: pre-allocates/reuses KKWebView instances
[Bridge Core]
- KKJSBridgeEngine: instantiates per WebView, holds configuration and module register
- Message Dispatch:
– JS → Native: via WKScriptMessageHandler
– Native → JS: via evaluateJavaScript callbacks
- KKJSBridgeMessage / KKJSBridgeMessageDispatcher: parse and route messages
[Module Layer]
- ModuleRegister & ModuleMetaClass: register and instantiate modules
- Built-in modules: AjaxHook, AjaxProtocolHook, FetchHook, Cookie, FormData, JS utilities
- AJAX Delegate Manager: delegate interface to perform network tasks (NSURLSession or AFNetworking)
[Network & Storage]
- NSURLProtocol hook (for protocol‐based interception)
- Native NSURLSession for sending real requests and returning data to JS
- NSHTTPCookieStorage for cookie management
[JavaScript Layer]
- TS/rollup build output (KKJSBridgeAJAXHook.js, KKJSBridgeAJAXProtocolHook.js, other hooks)
- window.KKJSBridge API, hook scripts injected at page load
- Local/offline HTML/JS resources (demo server files)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Native Plane
    subgraph "Native Plane"
        direction TB
        subgraph "Application Layer"
            direction TB
            DemoApp["Demo App (UIKit ViewControllers)"]:::demo
        end
        subgraph "WebView Layer"
            direction TB
            WebViewPool["KKWebViewPool"]:::native
            KKWebView["KKWebView (WKWebView subclass)"]:::native
        end
        subgraph "Bridge Core"
            direction TB
            Engine["KKJSBridgeEngine & Config"]:::native
            Dispatcher["Message Dispatcher"]:::native
        end
        subgraph "Module Layer"
            direction TB
            ModuleRegister["Module Registry"]:::native
            AjaxHookMod["AjaxHook Module"]:::native
            AjaxProtoMod["AjaxProtocolHook Module"]:::native
            FormDataMod["FormData Module"]:::native
            CookieMod["Cookie Module"]:::native
            DelegateMgr["AJAX Delegate Manager"]:::network
        end
        subgraph "Network & Storage"
            direction TB
            NSURLProtocolInt["NSURLProtocol interceptor"]:::network
            NSURLSession["NSURLSession"]:::network
            CookieStorage["NSHTTPCookieStorage"]:::network
            CookieManager["Cookie Manager"]:::native
        end
    end

    %% JS Plane
    subgraph "JS Plane"
        direction TB
        JSHooks["JS Hook Scripts"]:::js
        SSTDist["TS/rollup build output"]:::js
        ExternalServer["External HTTP Server"]:::js
    end

    %% Connections
    DemoApp -->|"dequeue/enqueue"| WebViewPool
    WebViewPool -->|"provides"| KKWebView
    KKWebView -->|"loads URL & injects hooks"| JSHooks
    JSHooks -->|"intercept XHR/fetch/formData"| Engine
    Engine -->|"WKScriptMessageHandler"| Dispatcher
    Dispatcher -->|"routes to"| ModuleRegister
    ModuleRegister -->|"instantiates"| AjaxHookMod
    ModuleRegister -->|"instantiates"| AjaxProtoMod
    ModuleRegister -->|"instantiates"| FormDataMod
    ModuleRegister -->|"instantiates"| CookieMod
    AjaxHookMod -->|"uses"| DelegateMgr
    AjaxProtoMod -->|"- - - optional"| NSURLProtocolInt
    DelegateMgr -->|"performs requests"| NSURLSession
    NSURLSession -->|"returns data"| DelegateMgr
    DelegateMgr -->|"response to"| AjaxHookMod
    AjaxHookMod -->|"evaluateJavaScript"| JSHooks
    CookieMod -->|"syncs"| CookieStorage
    CookieStorage -->|"syncs back"| CookieMod
    CookieMod -->|"uses"| CookieManager
    ExternalServer -->|"serves assets to"| KKWebView

    %% Click Events
    click DemoApp "https://github.com/karosli/kkjsbridge/blob/master/KKJSBridgeDemo/KKJSBridgeDemo/ViewController.h"
    click WebViewPool "https://github.com/karosli/kkjsbridge/blob/master/KKJSBridge/KKJSBridge/View/WebViewPool/KKWebViewPool.h"
    click KKWebView "https://github.com/karosli/kkjsbridge/blob/master/KKJSBridge/KKJSBridge/View/KKWebView.h"
    click Engine "https://github.com/karosli/kkjsbridge/blob/master/KKJSBridge/KKJSBridge/KKJSBridgeEngine.h"
    click Dispatcher "https://github.com/karosli/kkjsbridge/blob/master/KKJSBridge/KKJSBridge/Dispatcher/KKJSBridgeMessageDispatcher.h"
    click ModuleRegister "https://github.com/karosli/kkjsbridge/blob/master/KKJSBridge/KKJSBridge/Register/KKJSBridgeModuleRegister.h"
    click AjaxHookMod "https://github.com/karosli/kkjsbridge/blob/master/KKJSBridge/KKJSBridge/Modules/Ajax/AjaxHook/KKJSBridgeModuleXMLHttpRequestDispatcher.h"
    click AjaxProtoMod "https://github.com/karosli/kkjsbridge/blob/master/KKJSBridge/KKJSBridge/Modules/Ajax/AjaxProtocolHook/KKJSBridgeAjaxURLProtocol.h"
    click FormDataMod "https://github.com/karosli/kkjsbridge/blob/master/KKJSBridge/KKJSBridge/Modules/Ajax/FormData/KKJSBridgeFormDataFile.h"
    click CookieMod "https://github.com/karosli/kkjsbridge/blob/master/KKJSBridge/KKJSBridge/Modules/Cookie/KKJSBridgeModuleCookie.h"
    click DelegateMgr "https://github.com/karosli/kkjsbridge/blob/master/KKJSBridge/KKJSBridge/Modules/Ajax/KKJSBridgeAjaxDelegate.h"
    click CookieManager "https://github.com/karosli/kkjsbridge/blob/master/KKJSBridge/KKJSBridge/View/CookieManager/KKWebViewCookieManager.h"
    click JSHooks "https://github.com/karosli/kkjsbridge/blob/master/KKJSBridge/KKJSBridge/JS/KKJSBridgeAJAXHook.js"
    click ExternalServer "https://github.com/karosli/kkjsbridge/blob/master/KKJSBridgeDemo/KKJSBridgeDemo/Software/Server/server.js"

    %% Styles
    classDef native fill:#D0E8FF,stroke:#0066CC,color:#000;
    classDef network fill:#FFE0B2,stroke:#E65100,color:#000;
    classDef js fill:#E8F5E9,stroke:#2E7D32,color:#000;
    classDef demo fill:#F3E5F5,stroke:#6A1B9A,color:#000;
```
