# moukoublen/pick architecture

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

- Interactive diagram: https://gitdiagram.com/moukoublen/pick
- Repository: https://github.com/moukoublen/pick

## Overview

- API Interface Layer – This is where “Picker” lives (the primary exported API with functions like Bool(), String(), etc., and the Relaxed API variant). Include generics and the “Path” functions that allow the flexible field access.
- Conversion Module – Represent the “conv*.go” files that are responsible for converting different types (bool, int, string, etc.). You might also include the “numbers.go” and “pick.go” parts in this module.
- Traversal/Iteration Components – Represent the “traverse.go”, “iter” package (iter/iter.go), and mapping functions (Map, FlatMap, MapFilter, Each/EeachField). This component handles data traversal and iteration over arrays and objects.
- Error Handling – Include the core “error.go” and the internal error package (internal/errorsx) as well as the built-in error gathering mechanism (the ErrorsSink). This module shows how errors are captured and passed along (for both strict and relaxed APIs).
- Build and Tooling Scripts – Optionally show the “scripts” and “tools” directories to indicate the automated build, continuous integration, and code quality checks (referencing GitHub workflows and Makefile, for example).

##### Relationships and Data Flow
- The Conversion Module (which performs best effort conversion and type casting).
- The Traversal/Iteration module (which supports the dot/array notation navigation).
- The Error Handling component (to record and route errors either by returning errors or by using the relaxed API variant).
- Data flow by illustrating that user data (JSON or other structured data) is “wrapped” (via functions like WrapJSON) into a Picker object and then passed to the conversion and traversal modules.

##### Architectural Patterns and Design Principles
- Modularity – Separate components for conversion, traversal, and error handling.
- Extensibility – The use of generic functions (e.g., Get, RelaxedGet, Path, RelaxedPath) and modular converters allows for easy extension of the API.
- Best Effort Conversion – Emphasize how error management is central (via ErrorsSink and both strict/relaxed API paths) so that conversion and field access either return a useful default or a precise error.

##### Relevant Technologies and Tools
- Go Modules – Represent the go.mod and go.sum files as part of the environment.
- Testing – Show that several component tests are incorporated (like conv_bool_test.go, conv_int_test.go, etc.) to ensure the reliability.
- CI/CD Automation – Mark the GitHub workflows and scripts as external orchestration components for automated testing and tooling.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Input
    inputData["User JSON / Data"]:::input

    %% API Interface Layer
    subgraph "API Interface Layer"
        api["api.go"]:::api
        pick["pick.go"]:::api
        notation["notation.go"]:::api
    end

    %% Conversion Module
    subgraph "Conversion Module"
        conv["conv.go"]:::conv
        conv_bool["conv_bool.go"]:::conv
        conv_byte["conv_byte.go"]:::conv
        conv_duration["conv_duration.go"]:::conv
        conv_float["conv_float.go"]:::conv
        conv_int["conv_int.go"]:::conv
        conv_string["conv_string.go"]:::conv
        conv_time["conv_time.go"]:::conv
        conv_types["conv_types.go"]:::conv
        numbers["numbers.go"]:::conv
    end

    %% Traversal/Iteration Components
    subgraph "Traversal/Iteration Components"
        traverse["traverse.go"]:::traverse
        iter["iter/iter.go"]:::traverse
    end

    %% Error Handling
    subgraph "Error Handling"
        err["error.go"]:::error
        conv_err["conv_err.go"]:::error
        internal_err["internal/errorsx/errors.go"]:::error
    end

    %% Internal/Test Utilities
    subgraph "Internal/Test Utilities"
        tst["internal/tst"]:::test
        conv_bool_test["conv_bool_test.go"]:::test
        conv_int_test["conv_int_test.go"]:::test
        conv_string_test["conv_string_test.go"]:::test
        conv_test["conv_test.go"]:::test
        traverse_test["traverse_test.go"]:::test
        error_test["error_test.go"]:::test
    end

    %% Build and Tooling Scripts
    subgraph "Build and Tooling Scripts"
        scripts["scripts"]:::build
        github_workflows[".github/workflows"]:::build
        makefile["Makefile"]:::build
        tools["tools"]:::build
        golangci[".golangci.yml"]:::build
        codecov["codecov.yml"]:::build
    end

    %% Connections from external input to API
    inputData --> pick

    %% API Layer interactions
    pick -->|"access"| conv
    pick -->|"access"| traverse
    pick -->|"reports"| err

    %% Interactions between Conversion and Traversal Modules
    conv <-->|"bidirectional"| traverse

    %% Conversion and Traversal report errors
    conv --> err
    traverse --> err

    %% Dotted links from Build Scripts to core modules (CI/CD orchestration)
    scripts -.-> pick
    scripts -.-> conv
    scripts -.-> traverse
    scripts -.-> err
    github_workflows -.-> pick
    github_workflows -.-> conv
    github_workflows -.-> traverse
    github_workflows -.-> err

    %% Class Definitions for colors
    classDef api fill:#cef,stroke:#036,stroke-width:2px;
    classDef conv fill:#cfc,stroke:#090,stroke-width:2px;
    classDef traverse fill:#fc9,stroke:#c60,stroke-width:2px;
    classDef error fill:#fcc,stroke:#d00,stroke-width:2px;
    classDef test fill:#eee,stroke:#999,stroke-width:2px,stroke-dasharray:5,5;
    classDef build fill:#efe,stroke:#393,stroke-width:2px;
    classDef input fill:#f9d,stroke:#d2a,stroke-width:2px;

    %% Click Events for API Interface Layer
    click api "https://github.com/moukoublen/pick/blob/main/api.go"
    click pick "https://github.com/moukoublen/pick/blob/main/pick.go"
    click notation "https://github.com/moukoublen/pick/blob/main/notation.go"

    %% Click Events for Conversion Module
    click conv "https://github.com/moukoublen/pick/blob/main/conv.go"
    click conv_bool "https://github.com/moukoublen/pick/blob/main/conv_bool.go"
    click conv_byte "https://github.com/moukoublen/pick/blob/main/conv_byte.go"
    click conv_duration "https://github.com/moukoublen/pick/blob/main/conv_duration.go"
    click conv_float "https://github.com/moukoublen/pick/blob/main/conv_float.go"
    click conv_int "https://github.com/moukoublen/pick/blob/main/conv_int.go"
    click conv_string "https://github.com/moukoublen/pick/blob/main/conv_string.go"
    click conv_time "https://github.com/moukoublen/pick/blob/main/conv_time.go"
    click conv_types "https://github.com/moukoublen/pick/blob/main/conv_types.go"
    click numbers "https://github.com/moukoublen/pick/blob/main/numbers.go"

    %% Click Events for Traversal/Iteration Components
    click traverse "https://github.com/moukoublen/pick/blob/main/traverse.go"
    click iter "https://github.com/moukoublen/pick/blob/main/iter/iter.go"

    %% Click Events for Error Handling
    click err "https://github.com/moukoublen/pick/blob/main/error.go"
    click conv_err "https://github.com/moukoublen/pick/blob/main/conv_err.go"
    click internal_err "https://github.com/moukoublen/pick/blob/main/internal/errorsx/errors.go"

    %% Click Events for Internal/Test Utilities
    click tst "https://github.com/moukoublen/pick/tree/main/internal/tst"
    click conv_bool_test "https://github.com/moukoublen/pick/blob/main/conv_bool_test.go"
    click conv_int_test "https://github.com/moukoublen/pick/blob/main/conv_int_test.go"
    click conv_string_test "https://github.com/moukoublen/pick/blob/main/conv_string_test.go"
    click conv_test "https://github.com/moukoublen/pick/blob/main/conv_test.go"
    click traverse_test "https://github.com/moukoublen/pick/blob/main/traverse_test.go"
    click error_test "https://github.com/moukoublen/pick/blob/main/error_test.go"

    %% Click Events for Build and Tooling Scripts
    click scripts "https://github.com/moukoublen/pick/tree/main/scripts"
    click github_workflows "https://github.com/moukoublen/pick/tree/main/.github/workflows"
    click makefile "https://github.com/moukoublen/pick/tree/main/Makefile"
    click tools "https://github.com/moukoublen/pick/tree/main/tools"
    click golangci "https://github.com/moukoublen/pick/blob/main/.golangci.yml"
    click codecov "https://github.com/moukoublen/pick/blob/main/codecov.yml"
```
