# jhy/jsoup architecture

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

- Interactive diagram: https://gitdiagram.com/jhy/jsoup
- Repository: https://github.com/jhy/jsoup

## Overview

##### Main Components

a) Core API Layer
- Entry point (Jsoup.java)
- Connection interfaces
- Main public interfaces

b) Processing Layers
- Parser Layer
- DOM Layer
- Selection Layer
- Safety Layer

##### Component Details and Relationships

a) Input/Interface Layer:
- HTTP Connection handling (Connection.java, HttpConnection.java)
- Document input methods (URL, String, File)

b) Parser Component:
- Parser.java as the central component
- To subcomponents:
- Tokeniser
- TreeBuilder (both HTML and XML variants)
- CharacterReader

c) DOM Structure:
- Center around Document.java and Element.java
- Hierarchy of Node types:
- Elements
- TextNodes
- Comments
- DataNodes
- Use inheritance relationships

d) Selection/Query Layer:
- Selector.java as main component
- To:
- QueryParser
- Evaluator hierarchy
- Elements collection

e) Safety/Cleaning Layer:
- Cleaner.java
- Safelist.java
- As a separate but connected module

##### Specific Implementation Details

Key relationships:

**[Input Sources] → [Connection API] → [Parser]**
- ↓
**[Selector Engine] ← [DOM Structure] ← [TreeBuilder]**
- ↓
- [Elements Collection]
- ↓
- [Safety Cleaner]

##### Notes Section

Notes about:
- Thread safety considerations
- Memory management
- Performance characteristics
- Extension points

Remember to emphasize the library's key features:
- HTML parsing
- DOM manipulation
- CSS selection
- Safety cleaning
- URL fetching

This will provide a clear understanding of jsoup's architecture while maintaining the appropriate level of detail for a principal software engineer to understand both the high-level structure and important implementation details.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef core fill:#b3d1ff,stroke:#333
    classDef parser fill:#90EE90,stroke:#333
    classDef dom fill:#FFE5B4,stroke:#333
    classDef select fill:#FFA07A,stroke:#333
    classDef safety fill:#FFB6C1,stroke:#333
    
    %% Core API Layer
    subgraph CoreAPI["Core API Layer"]
        Jsoup["Jsoup"]:::core
        ConnInterface["Connection Interface"]:::core
        ConnImpl["HTTP Connection"]:::core
    end
    
    %% Parser Layer
    subgraph ParserLayer["Parser Layer"]
        Parser["Parser"]:::parser
        Tokeniser["Tokeniser"]:::parser
        CharReader["Character Reader"]:::parser
        HTMLBuilder["HTML Tree Builder"]:::parser
        XMLBuilder["XML Tree Builder"]:::parser
    end
    
    %% DOM Layer
    subgraph DOMLayer["DOM Layer"]
        Node["Node"]:::dom
        Document["Document"]:::dom
        Element["Element"]:::dom
        TextNode["Text Node"]:::dom
        Comment["Comment Node"]:::dom
        DataNode["Data Node"]:::dom
    end
    
    %% Selection Layer
    subgraph SelectionLayer["Selection Layer"]
        Selector["Selector Engine"]:::select
        QueryParser["Query Parser"]:::select
        Elements["Elements Collection"]:::select
        Evaluator["Evaluator"]:::select
    end
    
    %% Safety Layer
    subgraph SafetyLayer["Safety Layer"]
        Cleaner["Cleaner"]:::safety
        Safelist["Safelist"]:::safety
    end
    
    %% Relationships
    Jsoup --> ConnInterface
    ConnInterface --> ConnImpl
    Jsoup --> Parser
    Parser --> Tokeniser
    Parser --> CharReader
    Parser --> HTMLBuilder
    Parser --> XMLBuilder
    HTMLBuilder & XMLBuilder --> Document
    
    Document --> Node
    Element --> Node
    TextNode --> Node
    Comment --> Node
    DataNode --> Node
    
    Selector --> QueryParser
    Selector --> Evaluator
    Selector --> Elements
    Elements --> Element
    
    Document --> Cleaner
    Cleaner --> Safelist
    
    %% Click Events
    click Jsoup "https://github.com/jhy/jsoup/blob/master/src/main/java/org/jsoup/Jsoup.java"
    click ConnInterface "https://github.com/jhy/jsoup/blob/master/src/main/java/org/jsoup/Connection.java"
    click ConnImpl "https://github.com/jhy/jsoup/blob/master/src/main/java/org/jsoup/helper/HttpConnection.java"
    click Parser "https://github.com/jhy/jsoup/blob/master/src/main/java/org/jsoup/parser/Parser.java"
    click Tokeniser "https://github.com/jhy/jsoup/blob/master/src/main/java/org/jsoup/parser/Tokeniser.java"
    click CharReader "https://github.com/jhy/jsoup/blob/master/src/main/java/org/jsoup/parser/CharacterReader.java"
    click HTMLBuilder "https://github.com/jhy/jsoup/blob/master/src/main/java/org/jsoup/parser/HtmlTreeBuilder.java"
    click XMLBuilder "https://github.com/jhy/jsoup/blob/master/src/main/java/org/jsoup/parser/XmlTreeBuilder.java"
    click Document "https://github.com/jhy/jsoup/blob/master/src/main/java/org/jsoup/nodes/Document.java"
    click Element "https://github.com/jhy/jsoup/blob/master/src/main/java/org/jsoup/nodes/Element.java"
    click Node "https://github.com/jhy/jsoup/blob/master/src/main/java/org/jsoup/nodes/Node.java"
    click TextNode "https://github.com/jhy/jsoup/blob/master/src/main/java/org/jsoup/nodes/TextNode.java"
    click Comment "https://github.com/jhy/jsoup/blob/master/src/main/java/org/jsoup/nodes/Comment.java"
    click DataNode "https://github.com/jhy/jsoup/blob/master/src/main/java/org/jsoup/nodes/DataNode.java"
    click Selector "https://github.com/jhy/jsoup/blob/master/src/main/java/org/jsoup/select/Selector.java"
    click QueryParser "https://github.com/jhy/jsoup/blob/master/src/main/java/org/jsoup/select/QueryParser.java"
    click Elements "https://github.com/jhy/jsoup/blob/master/src/main/java/org/jsoup/select/Elements.java"
    click Evaluator "https://github.com/jhy/jsoup/blob/master/src/main/java/org/jsoup/select/Evaluator.java"
    click Cleaner "https://github.com/jhy/jsoup/blob/master/src/main/java/org/jsoup/safety/Cleaner.java"
    click Safelist "https://github.com/jhy/jsoup/blob/master/src/main/java/org/jsoup/safety/Safelist.java"
```
