# dart-archive/yaml_edit architecture

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

- Interactive diagram: https://gitdiagram.com/dart-archive/yaml_edit
- Repository: https://github.com/dart-archive/yaml_edit

## Overview

##### Project type and purpose
- This is an open-source Dart library/package (“yaml_edit”) whose sole purpose is to let users programmatically edit YAML documents in Dart while preserving comments and formatting.
- The README confirms: it exposes a `YamlEditor` API, uses unit & golden tests, and includes an example for JSON→YAML conversion.

##### File structure
- Top-level:
- pubspec.yaml (package metadata & dependencies)
- lib/ (public API and implementation)
- example/ (demo code)
- test/ (unit & golden tests + test data)
- CI configs under .github/
- `lib/`:
- yaml_edit.dart → exports the public API (`YamlEditor`)
- src/
– editor.dart → core orchestration: parse, apply edits, serialize
– list_mutations.dart & map_mutations.dart → high-level edit operations for lists/maps
– source_edit.dart → low-level text-edit tracking (insertion/deletion spans)
– wrap.dart & strings.dart → formatting helpers for output YAML
– utils.dart & equality.dart → auxiliary functions and deep-equality
– errors.dart → custom exception types
- `test/`: comprehensive coverage, including “golden tests” (input/output files under test/testdata)

##### README for additional insights
- Usage shows a simple edit workflow:
Input YAML string → `YamlEditor` → `update()` → `toString()` → Output YAML string
- Mentions limitations (no custom tags, map keys in flow style)

##### Elements
– Blue rectangles for core library modules (Editor, Mutation, SourceEdit, Serializer)
– Gray for external dependencies (YAML parser, dart:convert)
– Green for client/test code
– From client → API → Core → Mutations → SourceEdit → Serializer → back to client
– From CI → tests → modules
- **Labels** on each component with file names or class names (e.g., editor.dart → `Editor`)

##### Final advice
- Don’t overcomplicate: a few dozen components is fine—better to show every file group than to collapse everything.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client / Example"
        Example1["example.dart"]:::client
        Example2["json2yaml.dart"]:::client
    end

    subgraph "Public API Layer"
        API["yaml_edit.dart<br/>YamlEditor"]:::core
    end

    subgraph "Core Editor Layer"
        Editor["editor.dart<br/>Editor"]:::core
    end

    subgraph "Mutation Modules"
        ListMut["list_mutations.dart"]:::core
        MapMut["map_mutations.dart"]:::core
    end

    subgraph "SourceEdit Engine"
        SE["source_edit.dart<br/>SourceEdit"]:::core
    end

    subgraph "Serializer / Formatting"
        Wrap["wrap.dart"]:::core
        Str["strings.dart"]:::core
    end

    subgraph "Utilities"
        Utils["utils.dart"]:::core
        Eq["equality.dart"]:::core
    end

    Errors["errors.dart"]:::core

    subgraph "External Dependencies"
        Parser["package:yaml"]:::external
        DartConv["dart:convert"]:::external
    end

    subgraph "Tests & CI"
        Tests["test/*.dart"]:::client
        InputFD["testdata/input"]:::client
        OutputFD["testdata/output"]:::client
        CI[".github/workflows"]:::client
    end

    Example1 -->|"instantiate"| API
    Example2 -->|"instantiate"| API
    API -->|"invokes parser"| Parser
    API -->|"uses JSON conversion"| DartConv
    API -->|"calls"| Editor
    Editor -->|"routes edits"| ListMut
    Editor -->|"routes edits"| MapMut
    ListMut -->|"produce edits"| SE
    MapMut -->|"produce edits"| SE
    SE -->|"applies spans"| Wrap
    SE -->|"applies spans"| Str
    Wrap -->|"format output"| API
    Str -->|"format output"| API
    API -->|"returns YAML string"| Example1

    Editor -->|uses| Utils
    Editor -->|uses| Eq
    Editor -->|throws| Errors

    Tests -->|"drive modules"| Editor
    Tests -->|"drive modules"| ListMut
    Tests -->|"drive modules"| MapMut
    Tests -->|"drive modules"| SE
    Tests -->|"drive modules"| Wrap
    Tests -->|"drive modules"| Str
    CI -->|"triggers"| Tests

    classDef core fill:#A0C4FF,stroke:#000
    classDef external fill:#D3D3D3,stroke:#000
    classDef client fill:#C1E1C1,stroke:#000

    click API "https://github.com/dart-archive/yaml_edit/blob/main/lib/yaml_edit.dart"
    click Editor "https://github.com/dart-archive/yaml_edit/blob/main/lib/src/editor.dart"
    click ListMut "https://github.com/dart-archive/yaml_edit/blob/main/lib/src/list_mutations.dart"
    click MapMut "https://github.com/dart-archive/yaml_edit/blob/main/lib/src/map_mutations.dart"
    click SE "https://github.com/dart-archive/yaml_edit/blob/main/lib/src/source_edit.dart"
    click Wrap "https://github.com/dart-archive/yaml_edit/blob/main/lib/src/wrap.dart"
    click Str "https://github.com/dart-archive/yaml_edit/blob/main/lib/src/strings.dart"
    click Utils "https://github.com/dart-archive/yaml_edit/blob/main/lib/src/utils.dart"
    click Eq "https://github.com/dart-archive/yaml_edit/blob/main/lib/src/equality.dart"
    click Errors "https://github.com/dart-archive/yaml_edit/blob/main/lib/src/errors.dart"
    click Example1 "https://github.com/dart-archive/yaml_edit/blob/main/example/example.dart"
    click Example2 "https://github.com/dart-archive/yaml_edit/blob/main/example/json2yaml.dart"
    click Tests "https://github.com/dart-archive/yaml_edit/tree/main/test/"
    click InputFD "https://github.com/dart-archive/yaml_edit/tree/main/test/testdata/input/"
    click OutputFD "https://github.com/dart-archive/yaml_edit/tree/main/test/testdata/output/"
    click CI "https://github.com/dart-archive/yaml_edit/tree/main/.github/workflows/"
```
