# thihathit/rutter architecture

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

- Interactive diagram: https://gitdiagram.com/thihathit/rutter
- Repository: https://github.com/thihathit/rutter

## Overview

##### Main Components
- Core Router Engine:
– Modules found in the “core” directory (index.ts, normalizers.ts, router.ts, types.ts) encapsulate the primary routing logic such as route parsing, URL normalization, and state management.
– This is where the CreateHistory class is defined, which acts as the entry point to handle routes, URL changes, and reactive state.

- Bindings / Integration Layers:
– The “dev” folder contains sample applications (e.g., App.tsx, main.tsx, router.ts) demonstrating how to integrate the core into different frameworks.
– The README shows usage samples and implementation patterns for React, Vue, Svelte, and plain JavaScript. These represent lightweight adapters connecting framework-specific state management or reactivity to the router’s core.

- Utility Modules:
– The “utility” directory contains helper functions (functions.ts, url.ts) that might be used for additional processing, URL utilities, or common operations.

- Supporting Infrastructure:
– Directories like “docs” (with logos and other documentation material) and “scripts” (for build/package info generation) support development and release processes.
– The configuration files (.eslintrc, .prettierrc, tsconfig.json, etc.) are used for development and build tooling but are less central to the runtime architecture.

##### Relationships and Interactions
- The central router engine (CreateHistory instance) maintains the current state of routes (routeState and summaryState) and exposes helper functions (redirect, on, onOneOf, watchRouteState, watchSummaryState) to interact with the browser’s navigation APIs.
- The adapters or binding layers (as seen in the dev examples) subscribe to changes from the core router using the watch functions. They then update the UI state accordingly – this is typically achieved by React’s useState, Vue’s reactive utilities, or Svelte’s readable/derived stores.
- External consumers (applications using Rutter) interact with the router by invoking functions like redirect and by reading state updates communicated via reactive signals — this interaction loop ensures that navigation changes are propagated throughout the application.

##### Architectural Patterns and Design Principles
- Separation of Concerns:
– The core library is separate from its framework-specific bindings. This clean separation ensures that the routing logic remains framework-agnostic.
- Observer/Reactive Pattern:
– The library relies on reactive primitives (from Signals or framework-specific reactive utilities) to notify subscribed components when the routing state changes.
- API Abstractions:
– The design abstracts browser-native APIs (URLPattern, History) behind its own API (CreateHistory, on, redirect) to provide a unified interface for developers regardless of how they choose to integrate it.

##### Relevant Technologies, Frameworks, and Libraries
- Browser APIs: URLPattern and History for routing.
- React, Vue, and Svelte: Examples provided in the README show how the router is adapted for these frameworks.
- Utility Libraries: For example, lodash-es is used in Vue and Svelte binding examples.
- Prettier, ESLint, and other build and configuration tools support development.

##### Summary
- The central routing core that abstracts browser-native APIs and manages route state.
- The framework-specific binding layers that subscribe to the core’s reactive state changes and expose them in a way that is idiomatic to each target framework.
- The flow of data and user interactions: from route configuration through to state updates and reactive UI rendering.
- Extra development and tooling assets to give context to the project’s overall setup and quality measures.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User Navigation Event"]:::user

    subgraph "Framework Binding Layers"
        React["React Adapter"]:::binding
        Vue["Vue Adapter"]:::binding
        Svelte["Svelte Adapter"]:::binding
        Vanilla["VanillaJS Adapter"]:::binding
    end

    subgraph "Core Router Engine"
        Core_Index["Index"]:::core
        Core_Normalizers["Normalizers"]:::core
        Core_Router["Router (CreateHistory)"]:::core
        Core_Types["Types"]:::core
    end

    subgraph "Utility Modules"
        Util_Functions["Functions"]:::utility
        Util_URL["URL Utilities"]:::utility
        Util_Index["Utility Index"]:::utility
    end

    subgraph "Supporting Infrastructure"
        Docs["Documentation & Logos"]:::support
        Build["Build Scripts & Tooling"]:::support
        Config["Configuration Files"]:::support
    end

    BrowserAPIs["Browser APIs (URLPattern & History)"]:::external

    %% User flow to binding layers
    User -->|"triggers"| React
    User -->|"triggers"| Vue
    User -->|"triggers"| Svelte
    User -->|"triggers"| Vanilla

    %% Binding layers interact with Core Router Engine
    React -->|"invokes"| Core_Router
    Vue -->|"invokes"| Core_Router
    Svelte -->|"invokes"| Core_Router
    Vanilla -->|"invokes"| Core_Router

    %% Core Router Engine components interconnection
    Core_Router -->|"parses URL"| Core_Normalizers
    Core_Router -->|"manages state"| Core_Index
    Core_Router -->|"defines types"| Core_Types

    %% Core interacts with Browser APIs
    Core_Router -->|"calls"| BrowserAPIs
    BrowserAPIs -->|"updates via History"| Core_Router

    %% Core utilizes Utility Modules
    Core_Router -->|"normalizes URL using"| Util_URL
    Util_Functions ---|"shared helpers"| Core_Router

    %% Reactive update back to binding layers
    Core_Router ---|"reactive update"| React
    Core_Router ---|"reactive update"| Vue
    Core_Router ---|"reactive update"| Svelte
    Core_Router ---|"reactive update"| Vanilla

    %% Supporting Infrastructure connections (conceptual)
    Build ---|"builds"| Core_Router
    Config ---|"configures"| Core_Router
    Docs ---|"documents"| Core_Router

    %% Click Events for Core Router Engine
    click Core_Index "https://github.com/thihathit/rutter/blob/master/core/index.ts"
    click Core_Normalizers "https://github.com/thihathit/rutter/blob/master/core/normalizers.ts"
    click Core_Router "https://github.com/thihathit/rutter/blob/master/core/router.ts"
    click Core_Types "https://github.com/thihathit/rutter/blob/master/core/types.ts"

    %% Click Events for Framework Binding Layers
    click React "https://github.com/thihathit/rutter/blob/master/dev/App.tsx"
    click Vue "https://github.com/thihathit/rutter/blob/master/dev/main.tsx"
    click Svelte "https://github.com/thihathit/rutter/blob/master/dev/router.ts"
    click Vanilla "https://github.com/thihathit/rutter/blob/master/dev/App.tsx"

    %% Click Events for Utility Modules
    click Util_Functions "https://github.com/thihathit/rutter/blob/master/utility/functions.ts"
    click Util_URL "https://github.com/thihathit/rutter/blob/master/utility/url.ts"
    click Util_Index "https://github.com/thihathit/rutter/blob/master/utility/index.ts"

    %% Click Events for Supporting Infrastructure
    click Docs "https://github.com/thihathit/rutter/tree/master/docs/"
    click Build "https://github.com/thihathit/rutter/blob/master/scripts/build-package-info.ts"
    click Config "https://github.com/thihathit/rutter/blob/master/.eslintrc"

    %% Style Definitions
    classDef core fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef binding fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef utility fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef support fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef user fill:#f5c6cb,stroke:#721c24,stroke-width:2px;
```
