# dbiesecke/lilredirector architecture

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

- Interactive diagram: https://gitdiagram.com/dbiesecke/lilredirector
- Repository: https://github.com/dbiesecke/lilredirector

## Overview

##### Project Type and Purpose
- This is an open-source Cloudflare Workers library (“lilredirector”) that you embed into your Worker script to handle HTTP redirects at the edge.
- Key goal: take a simple `redirects.js` array of path→URL mappings (with support for path parameters), run on every fetch event, and either issue a redirect or render a read-only UI (HTML/JSON/M3U/MSX) under a configurable base path.

##### File Structure
- Top‐level files:
- package.json / tsconfig.json: Node + TypeScript configuration.
- README.md: usage, config, authentication.
- src/ directory (core code):
- index.ts – exports the main `redirector(event, redirects, config)` function.
- router.ts – matches incoming request paths to redirect rules, extracts parameters.
- template-*.ts/.js – HTML/UI rendering for dashboard (`template-index.ts`, `template-json.ts`, `template-m3u.js/ts`, `template-msx.ts`).
- template.ts – shared templating logic.
- types.ts – TypeScript definitions for config, redirects, responses.
- CI / Deployment: `.github/workflows/build.yml`, `.npmignore`, `.prettierrc`, license files.

##### Extract Insights from README
- Entry point: import `lilredirector` & your `redirects.js`, attach to `addEventListener('fetch')`.
- Configurable options: `baseUrl`, `basicAuthentication`, `removeTrailingSlashes`.
- Authentication: built-in Basic Auth or integrate Cloudflare Access.
- Default UI endpoint: `/_redirects` (serves built-in dashboard).

##### Main Components & Relationships
a. External Actors / Services
- Client (browser or HTTP client)
- (Optional) Cloudflare Access Zero-Trust authentication layer
b. Cloudflare Edge & Workers Runtime
- The serverless execution environment that receives HTTP requests.
c. Your User Worker Script
- `addEventListener('fetch', event => respondWith(handler(event)))`
- Imports `redirector` and `redirects` config.
d. lilredirector Module
- Core Handler (`index.ts`)
- Router (`router.ts`)
- UI Templates (HTML/JSON/M3U/MSX)
- Types & Config Logic
e. Redirect Rules Config
- Static array in `redirects.js` (or `.ts`) defining path patterns & targets.
f. Optional Auth Component
- Basic Auth middleware inside `redirector`
- Cloudflare Access sits in front of Worker (optional).
g. HTTP Responses
- 3xx Redirects
- 200 UI Page (HTML)
- 200 JSON/M3U/MSX output
- 4xx/5xx Errors

##### Data Flow / Interaction Steps
1. Client → HTTP Request → Cloudflare Edge
2. Edge → Worker Runtime → invokes your Worker Script `handler(event)`
3. `handler` calls `redirector(event, redirects, config)`
4. Inside `redirector`:
- If path under `baseUrl` → (optional auth) → serve UI via template modules
- Else route path through `router.ts` → match against `redirects` → build redirect Response
- If no match → `error` or falls back to other Worker code
5. `handler` returns the `Response` or handles `error`

##### Architectural Patterns & Principles
- Serverless / Event‐driven design
- Modular separation: Routing, Templating, Core Handler, Config
- Configuration‐driven behavior (baseUrl, auth, slash handling)
- Single Responsibility: each template file handles one output format

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    Client["Client (Browser/HTTP Client)"]:::external
    CloudflareAccess["Cloudflare Access (Optional)"]:::externalAuth

    %% Edge Network
    subgraph "Cloudflare Edge"
        Edge["Cloudflare Edge"]:::cloud
    end

    %% Serverless Runtime
    subgraph "Worker Runtime"
        WorkerRuntime["Serverless Execution"]:::runtime
        Handler["User Worker Script<br/>handler(event)"]:::script
    end

    %% lilredirector Library
    subgraph "lilredirector Library"
        Core["Core Handler<br/>redirector(event, redirects, config)"]:::lib
        BasicAuth["Basic Auth Middleware"]:::externalAuth
        Router["Router<br/>router.ts"]:::lib

        subgraph "UI Renderer"
            SharedTemplate["Shared Templating Logic<br/>template.ts"]:::templates
            TemplateIndex["HTML Dashboard<br/>template-index.ts"]:::templates
            TemplateJSON["JSON UI<br/>template-json.ts"]:::templates
            TemplateM3U["M3U Playlist<br/>template-m3u.ts/js"]:::templates
            TemplateMSX["MSX Output<br/>template-msx.ts"]:::templates
        end

        Types["Type Definitions<br/>types.ts"]:::config
    end

    %% Configuration & Project Files
    subgraph "Configuration & Project Files"
        Redirects["Redirects Config<br/>redirects.js/.ts"]:::configFile
        PackageJSON["package.json"]:::configFile
        TSConfig["tsconfig.json"]:::configFile
        README["README.md"]:::configFile
        CI[".github/workflows/build.yml"]:::configFile
        NPMIgnore[".npmignore"]:::configFile
        Prettier[".prettierrc"]:::configFile
        LicenseA["LICENSE_APACHE"]:::configFile
        LicenseM["LICENSE_MIT"]:::configFile
        GitIgnore[".gitignore"]:::configFile
    end

    %% HTTP Responses
    RedirectResponse["3xx Redirect Response"]:::response
    UIResponse["200 UI Page (HTML/JSON/M3U/MSX)"]:::response
    ErrorResponse["4xx/5xx Error Response"]:::response

    %% Data Flow
    Client -->|HTTP Request| CloudflareAccess
    CloudflareAccess -->|proxies| Edge
    Edge -->|invokes| Handler
    Handler -->|calls| Core
    Core -->|validate path under baseUrl| BasicAuth
    BasicAuth -->|on success| Core
    Core -->|route UI request| TemplateIndex
    Core -->|route UI request| TemplateJSON
    Core -->|route UI request| TemplateM3U
    Core -->|route UI request| TemplateMSX
    Core -->|use shared templates| SharedTemplate
    Core -->|route redirect request| Router
    Router -->|match| Redirects
    Router -->|no match| ErrorResponse
    Router -->|on match| RedirectResponse
    Core -->|returns| UIResponse
    Core -->|returns| RedirectResponse
    Core -->|on error| ErrorResponse

    %% Connections to Runtime
    Handler -->|returns| UIResponse
    Handler -->|returns| RedirectResponse
    Handler -->|returns| ErrorResponse

    %% Deployment Integration
    Handler -->|uses config files| PackageJSON
    Handler -->|uses config files| TSConfig
    Handler -->|references docs| README
    Handler -->|CI & linting| CI
    Handler -->|ignore rules| NPMIgnore
    Handler -->|format rules| Prettier
    Handler -->|licenses| LicenseA
    Handler -->|licenses| LicenseM
    Handler -->|git ignores| GitIgnore

    %% Click Events
    click Core "https://github.com/dbiesecke/lilredirector/blob/master/src/index.ts"
    click Router "https://github.com/dbiesecke/lilredirector/blob/master/src/router.ts"
    click TemplateIndex "https://github.com/dbiesecke/lilredirector/blob/master/src/template-index.ts"
    click TemplateJSON "https://github.com/dbiesecke/lilredirector/blob/master/src/template-json.ts"
    click TemplateM3U "https://github.com/dbiesecke/lilredirector/blob/master/src/template-m3u.ts"
    click TemplateMSX "https://github.com/dbiesecke/lilredirector/blob/master/src/template-msx.ts"
    click SharedTemplate "https://github.com/dbiesecke/lilredirector/blob/master/src/template.ts"
    click Types "https://github.com/dbiesecke/lilredirector/blob/master/src/types.ts"
    click PackageJSON "https://github.com/dbiesecke/lilredirector/blob/master/package.json"
    click TSConfig "https://github.com/dbiesecke/lilredirector/blob/master/tsconfig.json"
    click README "https://github.com/dbiesecke/lilredirector/blob/master/README.md"
    click CI "https://github.com/dbiesecke/lilredirector/blob/master/.github/workflows/build.yml"
    click NPMIgnore "https://github.com/dbiesecke/lilredirector/blob/master/.npmignore"
    click Prettier "https://github.com/dbiesecke/lilredirector/blob/master/.prettierrc"
    click LicenseA "https://github.com/dbiesecke/lilredirector/tree/master/LICENSE_APACHE"
    click LicenseM "https://github.com/dbiesecke/lilredirector/tree/master/LICENSE_MIT"
    click GitIgnore "https://github.com/dbiesecke/lilredirector/blob/master/.gitignore"

    %% Styles
    classDef external fill:#E8F1F2,stroke:#333,stroke-width:1px
    classDef externalAuth fill:#FFDDAA,stroke:#333,stroke-width:1px
    classDef cloud fill:#B3E5FC,stroke:#036,stroke-width:1px
    classDef runtime fill:#C8E6C9,stroke:#266,stroke-width:1px
    classDef script fill:#FFF9C4,stroke:#665,stroke-width:1px
    classDef lib fill:#D1C4E9,stroke:#422,stroke-width:1px
    classDef templates fill:#FFCCBC,stroke:#531,stroke-width:1px
    classDef config fill:#F0F4C3,stroke:#C3C30E,stroke-width:1px
    classDef configFile fill:#CFD8DC,stroke:#455A64,stroke-width:1px
    classDef response fill:#FFCDD2,stroke:#B71C1C,stroke-width:1px
```
