# kepano/defuddle architecture

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

- Interactive diagram: https://gitdiagram.com/kepano/defuddle
- Repository: https://github.com/kepano/defuddle

## Overview

##### Main Components
- Defuddle Engine – The heart of this library. It includes the core parsing functionality that takes in a DOM document and outputs an article object having properties like content, title, metadata, math content, and more.
- Elements Modules – Under the src/elements directory, you have several modules that handle specific parts of content standardization:
- Code: Handles formatting and standardization of code blocks.
- Headings: Manages the extraction and transformation of heading elements.
- Math Modules: (math.base.ts, math.core.ts, math.full.ts, math.ts) These modules deal with converting math content including MathML elements. The “full” bundle uses the advanced math libraries.
- Metadata Extraction & Constants – These modules (metadata.ts, constants.ts) deal with gathering page meta-data and defining important constants.
- Types & Interfaces – The types.ts file defines the contract for the article object and supports type safety across the system.
- Bundles – Two entry points are provided: one in src/index.ts for the core bundle and one in src/index.full.ts for the full bundle that integrates additional math conversion capabilities.

##### Relationships and Interactions between Components
- The consumer calls the Defuddle constructor (from src/defuddle.ts) with a DOM document (and optional settings such as debug) and then invokes the parse() method.
- The parse method orchestrates the process by calling several helper modules/functions:
- It delegates heading and code block standardization to the corresponding element modules.
- For math content, depending on whether the core or full bundle is used, different math conversion modules are invoked.
- Metadata extraction is integrated to produce the final article output.
- External integrations:
- In server-side usage, an external package (e.g., JSDOM) is used to create a DOM, which then is passed to Defuddle.
- In the full bundle, external libraries such as mathml-to-latex and temml are integrated.

##### Architectural Patterns and Design Principles
- Modularity – The clear separation into different modules (elements, metadata, constants, types) supports a modular, loosely-coupled architecture.
- Extensibility – The design anticipates future extensions (e.g., new element modules, additional metadata extraction, alternative math conversion).
- Bundle Variants – Separation between the “core” and “full” functionality shows the use of feature toggles/build-time decisions in the architecture.
- Configurability – Options such as debug mode indicate that the system is designed to run in various environments with customizable behavior.

##### Relevant Technologies/Frameworks
- Webpack – Indicate that Webpack is used for bundling.
- External libraries:
- For advanced math conversion in the full bundle (e.g., mathml-to-latex, temml).
- JSDOM for server-side HTML parsing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Bundle Selection
    subgraph "Bundle Selection"
        CB["Core Bundle"]:::bundle
        FB["Full Bundle"]:::bundle
    end

    %% External Input
    DOM["DOM Document"]:::external
    JSDOM["JSDOM (Server-side)"]:::external

    %% Central Processing
    Defuddle["Defuddle Engine (constructor & parse())"]:::defuddle

    %% Elements Modules
    subgraph "Elements Modules"
        Code["Code Module"]:::element
        Headings["Headings Module"]:::element
        subgraph "Math Processing Modules"
            MathBase["Math Base"]:::element
            MathCore["Math Core"]:::element
            MathFull["Math Full"]:::element
            MathOther["Math"]:::element
        end
    end

    %% Metadata and Types
    subgraph "Metadata and Config"
        Metadata["Metadata Extraction"]:::metadata
        Constants["Constants"]:::metadata
        Types["Types & Interfaces"]:::metadata
    end

    %% Output
    Article["Output Article Object"]:::defuddle

    %% External Math Libraries for Full Bundle
    ExternalMath["mathml-to-latex & temml (Full Bundle)"]:::external

    %% Connections from Bundles to Defuddle Engine
    CB -->|"initializes"| Defuddle
    FB -->|"initializes"| Defuddle

    %% DOM Input via JSDOM
    JSDOM -->|"creates"| DOM
    DOM -->|"input"| Defuddle

    %% Defuddle processing pipeline: calling element modules
    Defuddle -->|"processes"| Code
    Defuddle -->|"processes"| Headings
    Defuddle -->|"processes"| MathBase
    Defuddle -->|"processes"| MathCore
    Defuddle -->|"processes"| MathOther
    %% Full bundle math module activation
    FB -->|"activates"| MathFull

    %% Defuddle processing pipeline: metadata & types
    Defuddle -->|"extracts"| Metadata
    Defuddle -->|"uses"| Constants
    Defuddle -->|"enforces"| Types

    %% Aggregation into the final article object
    Code --> Article
    Headings --> Article
    MathBase --> Article
    MathCore --> Article
    MathFull --> Article
    MathOther --> Article
    Metadata --> Article
    Constants --> Article
    Types --> Article

    %% External math libraries integrated with full bundle processing
    FB -->|"integrates"| ExternalMath

    %% Styles
    classDef defuddle fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef element fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef metadata fill:#FFFFE0,stroke:#000,stroke-width:1px;
    classDef bundle fill:#D3D3D3,stroke:#000,stroke-width:1px;
    classDef external fill:#FFB6C1,stroke:#000,stroke-width:1px;

    %% Click Events
    click Defuddle "https://github.com/kepano/defuddle/blob/main/src/defuddle.ts"
    click Code "https://github.com/kepano/defuddle/blob/main/src/elements/code.ts"
    click Headings "https://github.com/kepano/defuddle/blob/main/src/elements/headings.ts"
    click MathBase "https://github.com/kepano/defuddle/blob/main/src/elements/math.base.ts"
    click MathCore "https://github.com/kepano/defuddle/blob/main/src/elements/math.core.ts"
    click MathFull "https://github.com/kepano/defuddle/blob/main/src/elements/math.full.ts"
    click MathOther "https://github.com/kepano/defuddle/blob/main/src/elements/math.ts"
    click Metadata "https://github.com/kepano/defuddle/blob/main/src/metadata.ts"
    click Constants "https://github.com/kepano/defuddle/blob/main/src/constants.ts"
    click Types "https://github.com/kepano/defuddle/blob/main/src/types.ts"
    click CB "https://github.com/kepano/defuddle/blob/main/src/index.ts"
    click FB "https://github.com/kepano/defuddle/blob/main/src/index.full.ts"
```
