# devxoul/urlnavigator architecture

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

- Interactive diagram: https://gitdiagram.com/devxoul/urlnavigator
- Repository: https://github.com/devxoul/urlnavigator

## Overview

##### Project type and purpose
- This is an open-source Swift library (URLNavigator) plus an example iOS app demonstrating how to use it.
- Its purpose is to provide a URL-driven navigation engine that maps URL patterns to view controllers or handler closures.

##### File-structure analysis
- Top-level “Sources” folder contains two separate modules:
- URLMatcher – parses and matches incoming URLs against registered patterns.
- URLNavigator – exposes the Navigator API, registration functions, and UIKit integration.
- “Example” folder is a standalone iOS app that consumes the library, showing how to register URL maps in AppDelegate, define view controllers, and trigger push/present/open.
- “Tests” folder holds unit tests for both URLMatcher and URLNavigator modules.
- CI/CD workflows, Podspec, Package.swift, and codecov.yml reveal support for CocoaPods, SwiftPM, and continuous integration.

##### Key architectural insights from the README
- Core functionality is layered: pattern matching (URLMatcher) underpins the navigation logic (URLNavigator).
- Clients register URL patterns to initializers or handlers; Navigator resolves patterns, extracts placeholders, instantiates or calls closures.
- Integration points with iOS: UIApplicationDelegate launch/open URL callbacks, UIViewController extensions to find topmost controller, optional wrapping in UINavigationController.
- Extensibility: custom value converters, pluggable NavigatorProtocol, and ability to register handlers anywhere (global, IoC container, composition root).

##### Main components and interactions
- Component A: URLMatcher module
- URLConvertible, URLMatcher, URLMatchResult, URLPathComponent, converters
- Responsibility: parse URL strings, match against patterns, extract typed placeholder values
- Component B: URLNavigator module
- Navigator, NavigatorProtocol, NavigatorDelegate, UIViewController+TopMostViewController, UIViewControllerType
- Responsibility: hold registry of patterns → handler mappings, coordinate push/present/open calls, resolve top view controller
- Component C: Example App
- AppDelegate (initializes Navigator, registers map via NavigationMap), ViewControllers (UserList, UserView), Views (cells), Models (User, Repo), Networking (GitHub API)
- Responsibility: consume Navigator API, demonstrate URL-driven navigation flows
- Component D: External systems
- UIKit (UINavigationController, UIViewController, UIApplicationDelegate)
- CocoaPods / Swift Package Manager (distribution)

Data flows and relationships
- AppDelegate → calls URLNavigationMap.initialize(navigator) → Navigator.register(pattern, handler)
- User triggers Navigator.push/open/present(“scheme://…”) → Navigator uses URLMatcher to match URL → retrieves values → either instantiates UIViewController or executes handler closure → UIKit pushes/presents the resulting VC
- Tests invoke URLMatcher.match() and Navigator.open() directly to assert behavior

##### Architectural patterns and principles
- Separation of concerns: matching logic isolated in URLMatcher, navigation orchestration in URLNavigator, consumption in Example
- Protocol-oriented design: NavigatorProtocol allows mocking, extension points for delegate
- Inversion of control: clients supply closure or conforming type to handle matched URLs
- Single responsibility: each class or file has a narrow, well-defined role

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "URLMatcher Module"
        direction TB
        UM(URLMatcher):::module
        UMC[URLConvertible]:::module
        UMM[URLMatchResult]:::module
        UPC[URLPathComponent]:::module
        UPMC[URLPathComponentMatchResult]:::module
    end

    subgraph "URLNavigator Module"
        direction TB
        UN(Navigator):::module
        UNP[NavigatorProtocol]:::module
        UND[NavigatorDelegate]:::module
        UVC[UIViewController+TopMostViewController]:::module
        UVT[UIViewControllerType]:::module
    end

    subgraph "Example App (URLNavigatorExample)"
        direction TB
        EA_App(AppDelegate):::example
        EA_Map(NavigationMap):::example
        EA_ULVC[UserListViewController]:::example
        EA_UVVC[UserViewController]:::example
        EA_UCell[UserCell]:::example
        EA_RCell[RepoCell]:::example
        EA_User[User Model]:::example
        EA_Repo[Repo Model]:::example
        EA_GH[GitHub API]:::example
        EA_HTTP[HTTP Client]:::example
        EA_Res[Resources]:::example
        EA_Info[Info.plist]:::example
        EA_Pod[Podfile]:::example
        EA_Xcode[xcodeproj]:::example
    end

    subgraph "External Dependencies"
        direction TB
        EX_UI(UIKit):::external
        EX_DP[CocoaPods/SwiftPM]:::external
    end

    subgraph "Tests"
        direction TB
        T_UMTests[URLMatcher Tests]:::tests
        T_UNTests[URLNavigator Tests]:::tests
    end

    %% Relationships
    EA_App -->|"initialize & register(pattern,handler)"| EA_Map
    EA_Map -->|"uses API"| UN
    EA_ULVC -->|"push/open URL"| UN
    EA_UVVC -->|"push/open URL"| UN

    UN -->|"match(url) → MatchResult"| UM
    UN -->|"present(vc)"| EX_UI
    UN -->|"push(vc)"| EX_UI

    T_UMTests -->|"test match() & converters"| UM
    T_UNTests -->|"test open() & delegate"| UN

    EA_GH -->|uses| EA_HTTP
    EA_Res -->|assets/storyboard| EA_Info

    %% Click Events for URLMatcher Module
    click UM "https://github.com/devxoul/urlnavigator/tree/master/Sources/URLMatcher"
    click UMC "https://github.com/devxoul/urlnavigator/blob/master/Sources/URLMatcher/URLConvertible.swift"
    click UMM "https://github.com/devxoul/urlnavigator/blob/master/Sources/URLMatcher/URLMatchResult.swift"
    click UPC "https://github.com/devxoul/urlnavigator/blob/master/Sources/URLMatcher/URLPathComponent.swift"
    click UPMC "https://github.com/devxoul/urlnavigator/blob/master/Sources/URLMatcher/URLPatchComponentMatchResult.swift"

    %% Click Events for URLNavigator Module
    click UN "https://github.com/devxoul/urlnavigator/blob/master/Sources/URLNavigator/Navigator.swift"
    click UNP "https://github.com/devxoul/urlnavigator/blob/master/Sources/URLNavigator/NavigatorProtocol.swift"
    click UND "https://github.com/devxoul/urlnavigator/blob/master/Sources/URLNavigator/NavigatorDelegate.swift"
    click UVC "https://github.com/devxoul/urlnavigator/blob/master/Sources/URLNavigator/UIViewController+TopMostViewController.swift"
    click UVT "https://github.com/devxoul/urlnavigator/blob/master/Sources/URLNavigator/UIViewControllerType.swift"

    %% Click Events for Example App
    click EA_App "https://github.com/devxoul/urlnavigator/blob/master/Example/Sources/AppDelegate.swift"
    click EA_Map "https://github.com/devxoul/urlnavigator/blob/master/Example/Sources/Navigator/NavigationMap.swift"
    click EA_User "https://github.com/devxoul/urlnavigator/blob/master/Example/Sources/Models/User.swift"
    click EA_Repo "https://github.com/devxoul/urlnavigator/blob/master/Example/Sources/Models/Repo.swift"
    click EA_GH "https://github.com/devxoul/urlnavigator/blob/master/Example/Sources/Networking/GitHub.swift"
    click EA_HTTP "https://github.com/devxoul/urlnavigator/blob/master/Example/Sources/Networking/HTTP.swift"
    click EA_ULVC "https://github.com/devxoul/urlnavigator/blob/master/Example/Sources/ViewControllers/UserListViewController.swift"
    click EA_UVVC "https://github.com/devxoul/urlnavigator/blob/master/Example/Sources/ViewControllers/UserViewController.swift"
    click EA_UCell "https://github.com/devxoul/urlnavigator/blob/master/Example/Sources/Views/UserCell.swift"
    click EA_RCell "https://github.com/devxoul/urlnavigator/blob/master/Example/Sources/Views/RepoCell.swift"
    click EA_Res "https://github.com/devxoul/urlnavigator/tree/master/Example/Sources/Resources"
    click EA_Info "https://github.com/devxoul/urlnavigator/blob/master/Example/Sources/Supporting Files/Info.plist"
    click EA_Pod "https://github.com/devxoul/urlnavigator/tree/master/Example/Podfile"
    click EA_Xcode "https://github.com/devxoul/urlnavigator/blob/master/Example/URLNavigatorExample.xcodeproj"

    %% Click Events for Tests
    click T_UMTests "https://github.com/devxoul/urlnavigator/blob/master/Tests/URLMatcherTests/URLMatcherTests.swift"
    click T_UNTests "https://github.com/devxoul/urlnavigator/blob/master/Tests/URLNavigatorTests/NavigatorTests.swift"

    %% Styles
    classDef module fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef example fill:#E6FFF2,stroke:#28a745,color:#28a745;
    classDef external fill:#F0F0F0,stroke:#6a737d,color:#6a737d;
    classDef tests fill:none,stroke:#d73a49,stroke-dasharray: 5 5,color:#d73a49;
```
