# kuberwastaken/fuzzy-redirect architecture

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

- Interactive diagram: https://gitdiagram.com/kuberwastaken/fuzzy-redirect
- Repository: https://github.com/kuberwastaken/fuzzy-redirect

## Overview

##### Project Type and Purpose
- This is an open-source, TypeScript-based npm library called fuzzy-redirect.
- Purpose: provide a fuzzy‐matching engine and framework integrations (React Router & Next.js) to automatically redirect mistyped URLs to the closest valid route.
- Key features: Levenshtein-based matching core, React hooks/components, Next.js hooks for both Pages and App routers, a CLI to auto-generate route lists, and full TypeScript support.

##### File Structure Analysis
- Top-level files:
- package.json, tsconfig*.json, jest.config.js – build, test, and publishing configuration
- README.md, CONTRIBUTING.md, LICENSE, CHANGELOG.md – documentation
- src/
- cli/generate.ts – CLI entry for route scanning & file generation
- core/fuzzy.ts – core matching logic (findClosestRoute, Levenshtein, thresholds)
- index.ts – main export façade
- next/index.ts & next/app.ts – Next.js Pages Router and App Router hooks
- react/index.ts & react/utils.ts – React Router hooks/components and helper to extract routes
- tests/ & test_failure.txt – Jest test cases validating core, React, and Next integrations.
- Build targets: CJS (tsconfig.cjs.json), ESM (tsconfig.esm.json), and type declarations (tsconfig.types.json).

##### README Insights
- Describes usage patterns in React & Next.js, the core API, configuration options, and the CLI generator workflow.
- Highlights dependencies (TypeScript, minimal external libs) and extension points (useFuzzyRedirect, useAppFuzzyRedirect, FuzzyRedirect component, findClosestRoute).

##### Main Components
a. Core Fuzzy Engine
– Module: src/core/fuzzy.ts
– Responsibility: calculate edit distances and pick the closest route.
b. Integration Layers
– React Integration: src/react
- Exposes useFuzzyRedirect hook, FuzzyRedirect component, extractRoutes utility.
– Next.js Integration: src/next
- Exposes useFuzzyRedirect for Pages Router (index.ts) and useAppFuzzyRedirect for App Router (app.ts).
c. CLI Generator
– Module: src/cli/generate.ts
– Responsibility: scan a codebase’s pages/ or app/ directory, build and emit a route‐list file (fuzzy-routes.ts).
d. Consumer Application
– React or Next.js app that imports fuzzy-redirect modules or the generated routes file
– Runs in browser, calls integration hooks/components to perform runtime redirection.
e. Build & Publish Pipeline
– TypeScript compiler produces CJS, ESM, and type files
– npm publish step, versioning driven by CHANGELOG.md and PUBLISHING.md

##### Relationships & Data Flow
- CLI Generator reads filesystem (pages/ or app/) → outputs route-list artifact
- Consumer App imports fuzzy-redirect API or generated routes → passes validRoutes to hooks/components
- Integration hook calls Core Fuzzy Engine → computes closest match for current URL
- If match found, integration triggers Router redirect (React Router or Next Router)
- Tests import each layer to validate behavior end-to-end

##### Architectural Patterns & Design Principles
- Single Responsibility: core fuzzy logic is decoupled from framework code
- Facade Pattern: index.ts re-exports public API for simplicity
- Plugin/Adapter: separate adapters for React and Next.js using the same core engine
- CLI as a build‐time tool, distinct from runtime libraries

##### Technologies & Frameworks
- TypeScript (strictly typed codebase, multi-target outputs)
- Jest for unit tests
- Node.js for CLI (npx entrypoint)
- React Router & Next.js routers at runtime

- Clear component names (e.g., CoreFuzzyEngine, ReactHookAdapter, NextPagesAdapter, CLI_Generator)
- Annotations for file paths (e.g., src/core/fuzzy.ts) if desired for precision

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build-Time CLI
    subgraph "Build-Time" 
        direction TB
        CLI["CLI Generator\nsrc/cli/generate.ts"]:::cli
        Artifact["Generated Route List\nfuzzy-routes.ts"]:::cli
    end

    %% Library Modules
    subgraph "Library Modules"
        direction TB
        PublicAPI["Public API Facade\nsrc/index.ts"]:::core
        Core["Core Fuzzy Engine\nsrc/core/fuzzy.ts"]:::core

        subgraph "React Adapter"
            direction TB
            ReactIndex["React Hooks & Component\nsrc/react/index.ts"]:::adapter
            ReactUtils["Route Extraction Utility\nsrc/react/utils.ts"]:::adapter
        end

        subgraph "Next.js Adapter"
            direction TB
            NextPages["Pages Router Hook\nsrc/next/index.ts"]:::adapter
            NextApp["App Router Hook\nsrc/next/app.ts"]:::adapter
        end
    end

    %% Consumer App
    Consumer["Consumer Application\n(React/Next.js)"]:::consumer

    %% Build & Publish Pipeline
    subgraph "Build & Publish Pipeline"
        direction TB
        CJS["tsconfig.cjs.json"]:::build
        ESM["tsconfig.esm.json"]:::build
        TYPES["tsconfig.types.json"]:::build
        PKG["package.json"]:::build
    end

    %% Test Suite
    Tests["Test Suite\ntests/"]:::tests

    %% Relationships
    CLI -->|route scan| Artifact
    Artifact -->|route list import| Consumer
    Consumer -->|imports API| PublicAPI
    Consumer -->|uses hook| ReactIndex
    Consumer -->|uses hook| NextPages
    Consumer -->|uses hook| NextApp

    PublicAPI -->|re-exports| ReactIndex
    PublicAPI -->|re-exports| ReactUtils
    PublicAPI -->|re-exports| NextPages
    PublicAPI -->|re-exports| NextApp
    PublicAPI -->|re-exports| Core

    ReactIndex -->|findClosestRoute| Core
    NextPages -->|findClosestRoute| Core
    NextApp -->|findClosestRoute| Core
    Core -->|redirect call| Consumer

    CJS --> PKG
    ESM --> PKG
    TYPES --> PKG

    Tests --> Core
    Tests --> ReactIndex
    Tests --> ReactUtils
    Tests --> NextPages
    Tests --> NextApp

    %% Click Events
    click CLI "https://github.com/kuberwastaken/fuzzy-redirect/blob/main/src/cli/generate.ts"
    click Artifact "https://github.com/kuberwastaken/fuzzy-redirect/blob/main/src/cli/generate.ts"
    click PublicAPI "https://github.com/kuberwastaken/fuzzy-redirect/blob/main/src/index.ts"
    click Core "https://github.com/kuberwastaken/fuzzy-redirect/blob/main/src/core/fuzzy.ts"
    click ReactIndex "https://github.com/kuberwastaken/fuzzy-redirect/blob/main/src/react/index.ts"
    click ReactUtils "https://github.com/kuberwastaken/fuzzy-redirect/blob/main/src/react/utils.ts"
    click NextPages "https://github.com/kuberwastaken/fuzzy-redirect/blob/main/src/next/index.ts"
    click NextApp "https://github.com/kuberwastaken/fuzzy-redirect/blob/main/src/next/app.ts"
    click CJS "https://github.com/kuberwastaken/fuzzy-redirect/blob/main/tsconfig.cjs.json"
    click ESM "https://github.com/kuberwastaken/fuzzy-redirect/blob/main/tsconfig.esm.json"
    click TYPES "https://github.com/kuberwastaken/fuzzy-redirect/blob/main/tsconfig.types.json"
    click PKG "https://github.com/kuberwastaken/fuzzy-redirect/blob/main/package.json"
    click Tests "https://github.com/kuberwastaken/fuzzy-redirect/tree/main/tests/"

    %% Styles
    classDef cli fill:#FFA500,stroke:#333,stroke-width:1px
    classDef core fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef adapter fill:#90EE90,stroke:#333,stroke-width:1px
    classDef consumer fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef build fill:#F0E68C,stroke:#333,stroke-width:1px
    classDef tests fill:#D8BFD8,stroke:#333,stroke-width:1px
```
