# mrspartak/html-ai-ready architecture

> Architecture diagram of the GitHub repository mrspartak/html-ai-ready, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mrspartak/html-ai-ready
- Repository: https://github.com/mrspartak/html-ai-ready

## Overview

##### Main Components
- Library API Layer: Represent the public interface (e.g., the exported function htmlToAiReady and preset constants like PRESET_QUALITY) which users import into their projects.
- Core Logic (TypeScript): Show the main logic in the src directory including utility modules (cleanup_html, simplified_markdown, striptag) and type definitions. This layer manages the conversion from HTML to an optimized text representation.
- Testing & Benchmarking: Include a component that represents the tests and benchmarks (tests directory) as these are crucial for validating both output quality and performance.
- Build & Configuration: Indicate support files such as package.json, tsconfig.json, tsup.config.ts, and GitHub workflows (in the .github directory), which are essential for building, testing, and deployment.

##### Relationships and Interactions
- The API Layer (the entry point from src/index.ts) calls into the Core Logic utilities which perform HTML cleanup and conversion.
- That the Documentation & Examples component is a support artifact which “consumes” or details the implementation of the above components.
- Finally, include a Build & Configuration section that feeds into both the API Layer and the Native Module, highlighting the build tools and scripts used to compile, bundle, and deploy the library.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clearly differentiate between the main API, the transformation utilities, and the native (performance) pathway.
- Modularity: Each folder (src, native, tests, docs) represents a module or layer that can be independently maintained and tested.
- Transparent Interoperability: The native module integrates with the JavaScript code through clearly defined bindings; visually indicate that with a connector between the TypeScript layer and the Rust/native layer.

##### Relevant Technologies, Frameworks, and Tools
- TypeScript (Node.js) is the primary language for the API and utility modules.
- Rust is used for the native module.
- Build Tools: tsup (for bundling), TypeScript configuration (tsconfig.json), and package managers (npm, pnpm, yarn, bun).
- Testing and CI Infrastructure: Vitest (as indicated by vitest.config.ts), and GitHub workflows for automated testing and releases.
- Documentation Tools: Typedoc (typedoc.json) and examples which guide users in leveraging the library’s capabilities.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Peripheral Data Flow Nodes
    HTMLInput["HTML Input"]:::source
    AIOutput["AI Ready Output"]:::output

    %% Core Application Logic
    subgraph "Core Application Logic"
        API["HTML AI Ready API"]:::api
        UTIL1["Cleanup HTML Utility"]:::utility
        UTIL2["Simplified Markdown Utility"]:::utility
        UTIL3["Striptag Utility"]:::utility
        TYPES["Core Types"]:::types
    end

    %% Native Module Layer
    subgraph "Native Module"
        NATIVE["Native Module (Rust + Node Bindings)"]:::native
    end

    %% Peripheral Components
    subgraph "Peripheral Components"
        TEST["Test & Benchmark Suite"]:::test
        DOCS["Documentation & Examples"]:::docs
        BUILD["Build & Config Tools"]:::build
    end

    %% Data Flow and Interactions
    HTMLInput -->|"ingests"| API
    API -->|"calls_utility"| UTIL1
    API -->|"calls_utility"| UTIL2
    API -->|"calls_utility"| UTIL3
    API --> TYPES
    API <-->|"Native_Preset_Call(HTML_TO_AI_NATIVE)"| NATIVE
    API -->|"outputs"| AIOutput

    TEST -->|"validates"| API
    TEST -->|"benchmarks"| NATIVE

    DOCS -->|"documents"| API
    DOCS -->|"describes"| UTIL1
    DOCS -->|"describes"| UTIL2
    DOCS -->|"describes"| UTIL3

    BUILD -->|"builds"| API
    BUILD -->|"builds"| NATIVE

    %% Click Events
    click API "https://github.com/mrspartak/html-ai-ready/blob/master/src/index.ts"
    click UTIL1 "https://github.com/mrspartak/html-ai-ready/blob/master/src/utilities/cleanup_html.ts"
    click UTIL2 "https://github.com/mrspartak/html-ai-ready/blob/master/src/utilities/simplified_markdown.ts"
    click UTIL3 "https://github.com/mrspartak/html-ai-ready/blob/master/src/utilities/striptag.ts"
    click TYPES "https://github.com/mrspartak/html-ai-ready/tree/master/src/types"
    click NATIVE "https://github.com/mrspartak/html-ai-ready/blob/master/native/src/lib.rs"
    click TEST "https://github.com/mrspartak/html-ai-ready/tree/master/tests"
    click DOCS "https://github.com/mrspartak/html-ai-ready/blob/master/docs/index.html"
    click BUILD "https://github.com/mrspartak/html-ai-ready/blob/master/package.json"

    %% Styles
    classDef api fill:#a8d8ea,stroke:#005f73,stroke-width:2px;
    classDef utility fill:#ffcc5c,stroke:#f6ab6c,stroke-width:2px;
    classDef types fill:#ff6f61,stroke:#ee4035,stroke-width:2px;
    classDef native fill:#b0e57c,stroke:#4caf50,stroke-width:2px;
    classDef test fill:#d3c0eb,stroke:#8e44ad,stroke-width:2px;
    classDef docs fill:#f7cac9,stroke:#b565a7,stroke-width:2px;
    classDef build fill:#c1e1c1,stroke:#2e7d32,stroke-width:2px;
    classDef source fill:#aad8d3,stroke:#008080,stroke-width:2px;
    classDef output fill:#ffd1dc,stroke:#ff69b4,stroke-width:2px;
```
