# udem-lbit/sowing architecture

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

- Interactive diagram: https://gitdiagram.com/udem-lbit/sowing
- Repository: https://github.com/udem-lbit/sowing

## Overview

##### Project Type and Purpose
- This is a specialized library (not a full-stack or distributed system) focused on representing and manipulating immutable trees.
- The README emphasizes immutable tree construction with a Node class, navigation using zippers (cursors), various tree traversals (depth-first, Euler, leaves), and utilities to serialize/deserialize (using Newick and JSON formats) along with combinatorial tree manipulation tools.
- It builds on functional “replace” semantics and ensures immutability throughout, meaning that every alteration creates a new instance of the tree.

##### Main Components
- Core Tree Data Structure: Represent the Node (and implicitly, Edge) components. This is the nucleus of the library.
- Navigational Component (Zipper/Cursor): Illustrate the unzip() and zip() mechanisms for navigating and modifying immutable trees.
- Representation Modules:
- Newick Parser/Writer: Shows bidirectional conversion between the tree data structure and the extended Newick format.
- JSON Serializer: Capturing alternative representations.
- Traversal and Transformation: Include the modules handling different traversal orders (depth, Euler, leaves) as well as transformation functions (map, fold).
- Indexed Trees: Demonstrate the additional layer of random access to tree nodes, crucial for lookup and LCA operations.
- Combinatorial Tools:
- Binary (binarize): For converting trees into binary representations.
- Supertree: For constructing a supertree that captures the topology shared by multiple trees.
- Utility Modules: Such as those for dataclass operations, partitioning, and range queries which support the main operations.

##### Relationships and Interactions
- Data flow starting from the Node (central core) that gets extended/modified using the Zipper (cursor navigation).
- How serialization modules (Newick and JSON) interact with the Node to output or input tree representations.
- That the combinatorial modules (binary and supertree) take an existing tree as input and output a transformed tree.
- In the “Indexed Trees” component, display that indexing wraps around the Node structure, providing fast lookups and relationship queries (like LCA, depth, distances).

##### Architectural Patterns and Design Principles
- Immutability: Emphasize that once a tree (or node) is constructed, any modifications produce a new tree via the zipper interface. This could be noted with an immutable symbol or label.
- Separation of Concerns: Each module (tree construction, navigation, traversal, serialization, combinatorial functions) handles a distinct aspect of tree manipulation.

##### Final Advice
- Every component is clearly and succinctly labeled.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Core Components
    subgraph "Core Components"
        CoreTree["Core Tree (Node & Edge)"]:::core
    end

    %% Navigation Layer
    subgraph "Navigation"
        Zipper["Zipper/Cursor"]:::navigation
    end

    %% Serialization Layer
    subgraph "Serialization"
        NewickParser["Newick Parser"]:::serialization
        NewickWriter["Newick Writer"]:::serialization
        JSONSerializer["JSON Serializer"]:::serialization
    end

    %% Traversal & Transformation Layer
    subgraph "Traversal & Transformation"
        Traversal["Traversal & Transformation"]:::traversal
    end

    %% Indexed Access Layer
    subgraph "Indexed Access"
        Indexed["Indexed Tree"]:::indexed
    end

    %% Combinatorial Tools Layer
    subgraph "Combinatorial Tools"
        Binary["Binary Binarization"]:::combinatorial
        Supertree["Supertree Construction"]:::combinatorial
    end

    %% Utility Modules Layer
    subgraph "Utility Modules"
        U1["Dataclasses Utility"]:::utilities
        U2["Partition Utility"]:::utilities
        U3["Range Query Utility"]:::utilities
    end

    %% Relationships
    CoreTree -->|"uses"| Zipper
    CoreTree -->|"serializes"| NewickParser
    CoreTree -->|"serializes"| NewickWriter
    CoreTree -->|"serializes"| JSONSerializer
    CoreTree -->|"traversed_by"| Traversal
    CoreTree -->|"indexed_by"| Indexed
    CoreTree -->|"converted_by"| Binary
    CoreTree -->|"converted_by"| Supertree

    %% Utilities support transformation
    Traversal -->|"applies"| U1
    Traversal -->|"applies"| U2
    Traversal -->|"applies"| U3

    %% Click Events
    click CoreTree "https://github.com/udem-lbit/sowing/blob/main/src/sowing/node.py"
    click Zipper "https://github.com/udem-lbit/sowing/blob/main/src/sowing/zipper.py"
    click NewickParser "https://github.com/udem-lbit/sowing/blob/main/src/sowing/repr/newick/parse.py"
    click NewickWriter "https://github.com/udem-lbit/sowing/blob/main/src/sowing/repr/newick/write.py"
    click JSONSerializer "https://github.com/udem-lbit/sowing/blob/main/src/sowing/repr/json.py"
    click Traversal "https://github.com/udem-lbit/sowing/blob/main/src/sowing/traversal.py"
    click Indexed "https://github.com/udem-lbit/sowing/blob/main/src/sowing/indexed.py"
    click Binary "https://github.com/udem-lbit/sowing/blob/main/src/sowing/comb/binary.py"
    click Supertree "https://github.com/udem-lbit/sowing/blob/main/src/sowing/comb/supertree.py"
    click U1 "https://github.com/udem-lbit/sowing/blob/main/src/sowing/util/dataclasses.py"
    click U2 "https://github.com/udem-lbit/sowing/blob/main/src/sowing/util/partition.py"
    click U3 "https://github.com/udem-lbit/sowing/blob/main/src/sowing/util/rangequery.py"

    %% Styles
    classDef core fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef navigation fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
    classDef serialization fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px;
    classDef traversal fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef indexed fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
    classDef combinatorial fill:#EBDEF0,stroke:#8E44AD,stroke-width:2px;
    classDef utilities fill:#D7BDE2,stroke:#5D6D7E,stroke-width:2px;
```
