# kdl-org/kdl-rs architecture

> Architecture diagram of the GitHub repository kdl-org/kdl-rs, 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/kdl-org/kdl-rs
- Repository: https://github.com/kdl-org/kdl-rs

## Overview

a. Primary Parse Flow:
- Input String → Parser (V1/V2) → Document Structure → Formatted Output

b. Query System Flow:
- Query String → Query Parser → Document → Matched Results

##### Component Relationships

a. Parser Layer:
- V1 and V2 parsers as parallel components
- Both to the core data structures
- Fallback mechanism when v1-fallback feature is enabled

b. Data Structure Layer:
- Hierarchical relationship: Document → Node → Entry → Value
- Identifier as a shared component used by multiple structures

- Span Feature (default)
- V1 Support
- V1 Fallback

##### Implementation Details

- Core parsing logic (blue)
- Data structures (green)
- Error handling (red)
- Formatting/output (purple)

##### External Interfaces

Integration points for:
- Miette error reporting
- Nom parser combinator compatibility
- Standard Rust traits (FromStr, Display)

##### Testing Components (Optional section)

A separate area showing:
- Compliance tests
- Formatting tests
- Query API tests

- The document-oriented nature of the parser
- The separation between parsing and formatting
- The ability to preserve formatting during edits
- The feature flag system
- Error handling with diagnostic capabilities

Keep the abstraction level focused on the architectural components while including enough detail to show the unique aspects of this KDL implementation, such as its formatting preservation and version compatibility features.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Parser Layer"
        V1["V1 Parser"]
        V2["V2 Parser"]
        QP["Query Parser"]
        NC["Nom Compatibility"]
    end

    subgraph "Core Data Structures"
        Doc["Document"]
        Node["Node"]
        Entry["Entry"]
        Val["Value"]
        Id["Identifier"]
    end

    subgraph "Error Handling"
        Err["Error System"]
        Miette["Miette Integration"]
    end

    subgraph "Formatting"
        Fmt["Formatter"]
    end

    subgraph "Testing"
        CT["Compliance Tests"]
        FT["Formatting Tests"]
        QT["Query API Tests"]
    end

    Input[/"Input String"/] --> V1
    Input --> V2
    QueryIn[/"Query String"/] --> QP

    V1 --> Doc
    V2 --> Doc
    QP --> Doc

    Doc --> Node
    Node --> Entry
    Entry --> Val
    Id --> Node
    Id --> Entry
    Id --> Val

    V1 -.-> Err
    V2 -.-> Err
    QP -.-> Err
    Err --> Miette

    Doc --> Fmt
    Fmt --> Output[/"Formatted Output"/]

    QP --> QueryRes[/"Matched Results"/]

    %% Component Mappings
    click V1 "https://github.com/kdl-org/kdl-rs/blob/main/src/v1_parser.rs"
    click V2 "https://github.com/kdl-org/kdl-rs/blob/main/src/v2_parser.rs"
    click QP "https://github.com/kdl-org/kdl-rs/blob/main/src/query_parser.rs"
    click NC "https://github.com/kdl-org/kdl-rs/blob/main/src/nom_compat.rs"
    click Doc "https://github.com/kdl-org/kdl-rs/blob/main/src/document.rs"
    click Node "https://github.com/kdl-org/kdl-rs/blob/main/src/node.rs"
    click Entry "https://github.com/kdl-org/kdl-rs/blob/main/src/entry.rs"
    click Val "https://github.com/kdl-org/kdl-rs/blob/main/src/value.rs"
    click Id "https://github.com/kdl-org/kdl-rs/blob/main/src/identifier.rs"
    click Err "https://github.com/kdl-org/kdl-rs/blob/main/src/error.rs"
    click Fmt "https://github.com/kdl-org/kdl-rs/blob/main/src/fmt.rs"
    click CT "https://github.com/kdl-org/kdl-rs/blob/main/tests/compliance.rs"
    click FT "https://github.com/kdl-org/kdl-rs/blob/main/tests/formatting.rs"
    click QT "https://github.com/kdl-org/kdl-rs/blob/main/tests/disabled_tests/query_api.rs"

    classDef parser fill:#a8d1ff,stroke:#333
    classDef dataStructure fill:#90EE90,stroke:#333
    classDef error fill:#ffb3b3,stroke:#333
    classDef formatter fill:#DDA0DD,stroke:#333
    classDef input fill:#f9f9f9,stroke:#333
    classDef testing fill:#FFE4B5,stroke:#333

    class V1,V2,QP,NC parser
    class Doc,Node,Entry,Val,Id dataStructure
    class Err,Miette error
    class Fmt formatter
    class Input,QueryIn,Output,QueryRes input
    class CT,FT,QT testing
```
