# sparklemotion/nokogiri architecture

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

- Interactive diagram: https://gitdiagram.com/sparklemotion/nokogiri
- Repository: https://github.com/sparklemotion/nokogiri

## Overview

##### Main Components
- Core API Layer – Represent the primary Nokogiri API housed in the “lib/nokogiri” directory. This layer includes the Ruby classes, modules, and DSLs (e.g., for CSS, XPath, HTML, XML, and XSLT handling).
- Java Extensions (JRuby) – Illustrate the “ext/java/nokogiri” folders that consist of Java source files and utilities. This component is essential for the JRuby implementation and integrates with dependencies like Xerces, NekoHTML, and additional JAR-based libraries.
- Test Suite – The “test/” directory contains extensive tests (for XML, HTML4, HTML5, CSS, and XPath). Represent this as an external quality gate that verifies and validates the interactions among components.

##### Relationships and Interactions
- The Gumbo Parser should be depicted as an external dependency that feeds into the HTML5 parsing functionality within the core APIs.

##### Architectural Patterns and Design Principles
- “thin wrapper” design: the Nokogiri API is a relatively thin layer that passes functionality directly through to underlying native libraries. Mark this with an annotation or note.
- The separation of concerns is clear: one component handles the Ruby-level DSLs (in “lib/”), while another handles platform-specific parsing implementations (in “ext/” for C and Java).
- The design is modular: the same high-level API endpoints function across different runtime environments (CRuby vs. JRuby).

##### Relevant Technologies and Frameworks
- Ruby (for the API and core logic).
- C (for native extensions on CRuby) and libxml2/libxslt (for parsing and transformation).
- Java (for JRuby implementations) along with associated XML libraries (e.g., Xerces, NekoHTML).
- Build/CI tools (Rake, GitHub Actions, Appveyor) – these should be noted as part of the development infrastructure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core API layer
    CoreAPI["Core Nokogiri API"]:::ruby

    %% Parsing Implementations: Native and Java Extensions
    subgraph "Parsing Implementations"
        NativeCRuby["Native Extensions (CRuby)"]:::native
        JavaJRuby["Java Extensions (JRuby)"]:::java
    end

    %% External Dependency for underlying libraries
    ExternalDep["External Dependencies<br/>(libxml2, libxslt, Xerces, NekoHTML)"]:::external

    %% Gumbo Parser Integration
    Gumbo["Gumbo Parser Integration"]:::external

    %% Test Suite
    TestSuite["Test Suite"]:::test

    %% Build & Deployment Infrastructure
    BuildInfra["Build & Deployment Infrastructure"]:::infra

    %% Thin wrapper annotation
    Note["Thin Wrapper Design<br/>(API acts as pass-through)"]:::external

    %% Relationships
    CoreAPI -->|"if CRuby"| NativeCRuby
    CoreAPI -->|"if JRuby"| JavaJRuby
    CoreAPI -->|"uses"| Gumbo

    NativeCRuby -->|"calls"| ExternalDep
    JavaJRuby -->|"calls"| ExternalDep

    TestSuite ---|"tests"| CoreAPI
    TestSuite ---|"tests"| NativeCRuby
    TestSuite ---|"tests"| JavaJRuby
    TestSuite ---|"tests"| Gumbo

    BuildInfra ---|"supports"| CoreAPI
    BuildInfra ---|"supports"| NativeCRuby
    BuildInfra ---|"supports"| JavaJRuby
    BuildInfra ---|"supports"| Gumbo

    CoreAPI --- Note

    %% Click Events for Component Mapping
    click CoreAPI "https://github.com/sparklemotion/nokogiri/tree/main/lib/nokogiri"
    click NativeCRuby "https://github.com/sparklemotion/nokogiri/tree/main/ext/nokogiri"
    click JavaJRuby "https://github.com/sparklemotion/nokogiri/tree/main/ext/java/nokogiri"
    click Gumbo "https://github.com/sparklemotion/nokogiri/tree/main/gumbo-parser"
    click TestSuite "https://github.com/sparklemotion/nokogiri/tree/main/test"
    click BuildInfra "https://github.com/sparklemotion/nokogiri/tree/main/doc"

    %% Styles
    classDef ruby fill:#FFD700,stroke:#B8860B,stroke-width:2px;
    classDef native fill:#ADD8E6,stroke:#00008B,stroke-width:2px;
    classDef java fill:#90EE90,stroke:#006400,stroke-width:2px;
    classDef external fill:#FFB6C1,stroke:#8B0000,stroke-width:2px;
    classDef test fill:#87CEFA,stroke:#4682B4,stroke-width:2px;
    classDef infra fill:#DDA0DD,stroke:#800080,stroke-width:2px;
```
