# huolalatech/hll-wp-therouter-ios architecture

> Architecture diagram of the GitHub repository huolalatech/hll-wp-therouter-ios, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/huolalatech/hll-wp-therouter-ios
- Repository: https://github.com/huolalatech/hll-wp-therouter-ios

## Overview

##### Project Type and Purpose
- This repository is an **iOS routing library** (“TheRouter”) with accompanying **demo applications** (Swift Example and Objective-C Example).
- It provides a modular, protocol-oriented URL‐based navigation and service invocation framework for decoupling iOS app components, supporting both Swift and Objective-C.

##### File-Structure Analysis
Top-level:
- `.gitignore`, `.travis.yml`, `LICENSE`, `README.md` – CI/configuration and documentation.
- `Example/…` – Swift demo app showing how an end consumer integrates and exercises TheRouter.
- `TheRouter-ObjectiveCDemo/…` – Objective-C demo app with CocoaPods setup and Bridging Headers.
- `TheRouter/…` – Core framework sources:
– `Classes/` – Swift + Obj-C source files for TheRouter runtime (Manager, Parser, ServiceManager, Builder, Interceptor, DebugTool, etc.).
– `Assets/` – placeholder for resource assets in the pod.
– `TheRouterable/` – SPM package for the `TheRouterable` protocol.
– `TheRouterMacro/` – Swift Package manifest and code for a CLI/macro that can generate boilerplate or assist routing registration.
- `TheRouter.podspec` – Podspec for CocoaPods distribution.
- `_Pods.xcodeproj` – aggregated workspace for local development/testing of the pod.

##### Architectural Insights from README
- **Core responsibilities**:
1. **Lazy route registration** via runtime class scanning (`objc_copyClassNames…`) and filtering by prefix.
2. **Pattern→ViewController mapping** driven by `TheRouterable` or `CustomRouterInfo` protocols.
3. **URL parsing and builder** (`TheRouterParser`, `TheRouterBuilder`) for chainable parameter setting.
4. **Navigation dispatch** (push/present/tabBar/modal) handled by `LARouterPresentController` extension points.
5. **Service discovery/injection** via `TheRouterServiceProtocol` and `TheRouterServiceManager`.
6. **Dynamic features**: interceptors, redirections, hot path repair, runtime add/remove routes, caching, global failure handling, compatibility with OC classes (`TheRouterableProxy`).

##### Main Components and Their Relationships
A. **Host App** (Example or Objective-C Demo)
– Calls `TheRouter.lazyRegisterRouterHandle` on launch.
– Invokes navigation: `TheRouter.openURL()`, `TheRouterBuilder.build().navigation()`.
– Fetches services: `TheRouter.fetchService(...)`.
B. **Router Core** (TheRouter Pod)
1. **RouterManager**
- Manages registration lifecycle (lazy vs. cache).
- Coordinates scanning and adding routes/services.
2. **PatternRegistry**
- Stores mapping of URL patterns ↔ class names.
3. **Parser & Builder**
- Parses incoming URL strings.
- Provides chainable parameter APIs.
4. **Navigation Controller Extensions**
- `LARouterPresentController` chooses push/present logic.
5. **ServiceManager**
- Registers and retrieves service implementations by protocol name.
6. **Interceptor & Redirection Handlers**
- Allow pre-navigation logic and dynamic path remapping.
7. **Debug & Logging**
- `TheRouterDebugTool` and log callback entry point.
C. **Macro/Codegen** (TheRouterMacro)
– SPM target that can generate routing boilerplate or assist in code instrumentation.
– Invoked at build time to emit static constants or convenience APIs.
D. **External Dependencies**
– **CocoaPods / SPM** distribution mechanism.
– iOS SDK (UIKit navigation stacks).
– Objective-C runtime APIs (`objc_copyClassNamesForImage`, `NSClassFromString`).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host App - Swift
    subgraph "Host App (Swift Example)"
        SwiftAppAppDelegate["AppDelegate.swift"]:::hostApp
        SwiftAppRouterAPI["TheRouterApi.swift"]:::hostApp
        SwiftAppPresentController["LARouterPresentController.swift"]:::hostApp
        SwiftAppDemoVC["Demo ViewControllers"]:::hostApp
        MainStoryboard["Main.storyboard"]:::hostApp
        LaunchScreen["LaunchScreen.xib"]:::hostApp
    end

    %% Host App - Objective-C
    subgraph "Host App (Objective-C Demo)"
        ObjCAppDelegate["AppDelegate.h/.m"]:::hostApp
        ObjCSceneDelegate["SceneDelegate.h/.m"]:::hostApp
        ObjCVC["ViewController.h/.m"]:::hostApp
        ObjCOpenRouter["OpenRouter/*"]:::hostApp
    end

    %% Router Core
    subgraph "Router Core (TheRouter Pod)"
        Manager["TheRouterManager.swift"]:::core
        PatternReg["TheRouterPattern.swift"]:::core
        Parser["TheRouterParser.swift"]:::core
        Builder["TheRouterBuilder.swift"]:::core
        NavExt["LARouterPresentController Extension"]:::core
        ServiceMgr["TheRouterServiceManager.swift"]:::core
        Interceptor["TheRouterInterceptor.swift"]:::core
        DebugTool["TheRouterDebugTool.swift"]:::core
        Bridge["TheRouerBridge.swift"]:::core
        DynParams["TheRouterDynamicParamsMapping.h"]:::core
        Extension["TheRouterExtension.swift"]:::core
    end

    %% Macro / Codegen
    subgraph "Macro / Codegen (TheRouterMacro)"
        MacroSPMPkg["Package.swift"]:::macro
        MacroClient["main.swift"]:::macro
        MacroMacros["TheRouterMacroMacro.swift"]:::macro
    end

    %% External Dependencies
    subgraph "External Dependencies"
        CocoaPods["CocoaPods / SPM"]:::external
        iOSSDK["iOS SDK (UIKit)"]:::external
        ObjCRuntime["Objective-C Runtime APIs"]:::external
        Podspec["TheRouter.podspec"]:::external
        Workspace["_Pods.xcodeproj"]:::external
    end

    %% Flows - Swift App integration
    SwiftAppAppDelegate -->|".lazyRegisterRouterHandle"| Manager
    Manager -->|"scan classes"| PatternReg
    Manager -->|"register services"| ServiceMgr
    SwiftAppRouterAPI -->|".openURL()"| Parser
    Parser -->|".parse()"| Builder
    Builder -->|".navigation()"| NavExt
    NavExt -->|"push/present"| SwiftAppDemoVC
    SwiftAppRouterAPI -->|".fetchService()"| ServiceMgr
    ServiceMgr -->|"return service impl"| SwiftAppDemoVC
    Manager ---|".interceptor check"| Interceptor
    Manager ---|".log events"| DebugTool

    %% Flows - Macro
    MacroSPMPkg -.->|build-time| Manager
    MacroSPMPkg -.->|generate boilerplate| PatternReg

    %% External
    CocoaPods -->|install Pod| SwiftAppAppDelegate
    CocoaPods -->|install Pod| ObjCAppDelegate
    iOSSDK -->|navigation APIs| NavExt
    ObjCRuntime -->|class scanning| Manager
    ObjCRuntime -->|NSClassFromString| Parser
    Podspec -.->|distribution| CocoaPods
    Workspace -.->|local dev| Manager

    %% Click Events - Swift
    click SwiftAppAppDelegate "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/Example/TheRouter/AppDelegate.swift"
    click SwiftAppPresentController "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/Example/TheRouter/LARouterPresentController.swift"
    click SwiftAppRouterAPI "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/Example/TheRouter/TheRouterApi.swift"
    click SwiftAppDemoVC "https://github.com/huolalatech/hll-wp-therouter-ios/tree/master/Example/TheRouter"
    click MainStoryboard "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/Example/TheRouter/Main.storyboard"
    click LaunchScreen "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/Example/TheRouter/Base.lproj/LaunchScreen.xib"

    %% Click Events - Objective-C
    click ObjCAppDelegate "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/TheRouter-ObjectiveCDemo/TheRouter-ObjectiveCDemo/AppDelegate.h"
    click ObjCSceneDelegate "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/TheRouter-ObjectiveCDemo/TheRouter-ObjectiveCDemo/SceneDelegate.h"
    click ObjCVC "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/TheRouter-ObjectiveCDemo/TheRouter-ObjectiveCDemo/ViewController.h"
    click ObjCOpenRouter "https://github.com/huolalatech/hll-wp-therouter-ios/tree/master/TheRouter-ObjectiveCDemo/TheRouter-ObjectiveCDemo/OpenRouter"

    %% Click Events - Router Core
    click Manager "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/TheRouter/Classes/TheRouterManager.swift"
    click PatternReg "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/TheRouter/Classes/TheRouterPattern.swift"
    click Parser "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/TheRouter/Classes/TheRouterParser.swift"
    click Builder "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/TheRouter/Classes/TheRouterBuilder.swift"
    click NavExt "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/Example/TheRouter/LARouterPresentController.swift"
    click ServiceMgr "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/TheRouter/Classes/TheRouterServiceManager.swift"
    click Interceptor "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/TheRouter/Classes/TheRouterInterceptor.swift"
    click DebugTool "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/TheRouter/Classes/TheRouterDebugTool.swift"
    click Bridge "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/TheRouter/Classes/TheRouerBridge.swift"
    click DynParams "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/TheRouter/Classes/TheRouterDynamicParamsMapping.h"
    click Extension "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/TheRouter/Classes/TheRouterExtension.swift"

    %% Click Events - Macro
    click MacroSPMPkg "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/TheRouterMacro/Package.swift"
    click MacroClient "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/TheRouterMacro/Sources/TheRouterMacroClient/main.swift"
    click MacroMacros "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/TheRouterMacro/Sources/TheRouterMacroMacros/TheRouterMacroMacro.swift"

    %% Click Events - External
    click Podspec "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/TheRouter.podspec"
    click Workspace "https://github.com/huolalatech/hll-wp-therouter-ios/blob/master/_Pods.xcodeproj"

    %% Styles
    classDef hostApp fill:#cce5ff,stroke:#3399ff,color:#000
    classDef core fill:#d4edda,stroke:#2e7d32,color:#000
    classDef macro fill:#ffe5b4,stroke:#ff8c00,color:#000
    classDef external fill:#f8f9fa,stroke:#6c757d,color:#000
```
