# gastrodon/psyduck architecture

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

## Overview

##### High-Level Components
- CLI / Entrypoint (main.go)
- Configuration Loader & DSL Parser (configure/*)
- Core Pipeline Builder & Runner (core/*)
- Plugin Registry & Standard Library (stdlib/*)
- Example Usage (examples/*) – ancillary, for reference only

##### Public Functions to Components

a. CLI / Entrypoint (main.go)
– main()
– init() (if any)

b. configure package
– Read(path string) (reads HCL or YAML)
– Parse(raw []byte) (returns AST / pipeline model)
– EvalContext(model *Model) (prepares evaluation context)
– Pipelines(model *Model) ([]*PipelineSpec)
– PluginLoader(files []string) (discovers & loads compiled plug-ins)

c. core package
– Build(pipelines []*PipelineSpec) (*BuiltPipeline)
– Run(bp *BuiltPipeline) error
– decodeAttributes(node *NodeSpec) (called inside Build)
– decodeBody(node *NodeSpec)
– validateNode(node *NodeSpec)

d. stdlib package
Subpackages and their factory functions:
– produce/Constant(name, value) ProducerFunc
– produce/Increment(name, start) ProducerFunc
– transform/Inspect(name, field) TransformerFunc
– transform/Sprintf(name, fmtStr) TransformerFunc
– transform/Transpose(name, key, value) TransformerFunc
– transform/Zoom(name, factor) TransformerFunc
– consume/Trash(name) ConsumerFunc
– plugin.go: RegisterStdlib()

##### Call Relationships

main → configure.Read → configure.Parse → configure.EvalContext
configure.EvalContext → configure.Pipelines → core.Build
core.Build → decodeAttributes, decodeBody, validateNode
core.Build → stdlib.plugin.RegisterStdlib (register built-in plug-ins)
core.Run → each pipeline’s node.RunFunc (producer/transformer/consumer)
node.RunFunc → appropriate stdlib function (e.g., produce.Constant)

##### Architectural Patterns
- Plug-in architecture: show stdlib.plugin.RegisterStdlib hooking into the core’s library registry.
- DSL → AST → in-memory model → pipeline graph (clearly annotate parse → model → Build stages).
- Pipeline as a directed graph: indicate many-to-many producers, transformers, consumers.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Component Boxes
    subgraph "CLI / Entrypoint"
        direction TB
        main["main()"]:::cli
    end

    subgraph "Configuration Loader & DSL Parser"
        direction TB
        Read["Read(path string)"]:::configure
        Parse["Parse(raw []byte)"]:::configure
        EvalContext["EvalContext(model *Model)"]:::configure
        Pipelines["Pipelines(model *Model)"]:::configure
        PluginLoader["PluginLoader(files []string)"]:::configure
    end

    subgraph "Core Pipeline Builder & Runner"
        direction TB
        Build["Build(pipelines []*PipelineSpec)"]:::core
        Run["Run(bp *BuiltPipeline)"]:::core
        decodeAttributes["decodeAttributes(node *NodeSpec)"]:::core
        decodeBody["decodeBody(node *NodeSpec)"]:::core
        validateNode["validateNode(node *NodeSpec)"]:::core
        RegisterStdlib["RegisterStdlib()"]:::core
    end

    subgraph "Plugin Registry & Standard Library"
        direction TB
        subgraph produce
            Constant["produce.Constant(name, value)"]:::stdlib
            Increment["produce.Increment(name, start)"]:::stdlib
        end
        subgraph transform
            Inspect["transform.Inspect(name, field)"]:::stdlib
            Sprintf["transform.Sprintf(name, fmtStr)"]:::stdlib
            Transpose["transform.Transpose(name, key, value)"]:::stdlib
            Zoom["transform.Zoom(name, factor)"]:::stdlib
        end
        subgraph consume
            Trash["consume.Trash(name)"]:::stdlib
        end
        RegisterStdlibStd["RegisterStdlib()"]:::stdlib
    end

    subgraph "Example Usage"
        examples["examples/*"]:::external
    end

    %% Call Relationships
    main -->|"calls"| Read
    Read -->|"calls"| Parse
    Parse -->|"calls"| EvalContext
    EvalContext -->|"calls"| Pipelines
    Pipelines -->|"calls"| Build

    Build -->|"calls"| decodeAttributes
    Build -->|"calls"| decodeBody
    Build -->|"calls"| validateNode
    Build -->|"registers plugins"| RegisterStdlib

    Run -->|"invokes node.RunFunc"| Constant
    Run -->|"invokes node.RunFunc"| Increment
    Run -->|"invokes node.RunFunc"| Inspect
    Run -->|"invokes node.RunFunc"| Sprintf
    Run -->|"invokes node.RunFunc"| Transpose
    Run -->|"invokes node.RunFunc"| Zoom
    Run -->|"invokes node.RunFunc"| Trash

    examples -->|"uses"| main
    examples -->|"references"| Pipelines
    examples -->|"executes"| Run

    %% Click Events
    click main "https://github.com/gastrodon/psyduck/blob/main/main.go"
    click Read "https://github.com/gastrodon/psyduck/blob/main/configure/read.go"
    click Parse "https://github.com/gastrodon/psyduck/blob/main/configure/parse.go"
    click EvalContext "https://github.com/gastrodon/psyduck/blob/main/configure/eval_ctx.go"
    click Pipelines "https://github.com/gastrodon/psyduck/blob/main/configure/pipelines.go"
    click PluginLoader "https://github.com/gastrodon/psyduck/blob/main/configure/plugin.go"
    click Build "https://github.com/gastrodon/psyduck/blob/main/core/build.go"
    click Run "https://github.com/gastrodon/psyduck/blob/main/core/run.go"
    click decodeAttributes "https://github.com/gastrodon/psyduck/blob/main/core/decode_attributes.go"
    click decodeBody "https://github.com/gastrodon/psyduck/blob/main/core/decode_body.go"
    click validateNode "https://github.com/gastrodon/psyduck/blob/main/core/decode_validate.go"
    click RegisterStdlib "https://github.com/gastrodon/psyduck/blob/main/core/library.go"
    click RegisterStdlibStd "https://github.com/gastrodon/psyduck/blob/main/stdlib/plugin.go"
    click Constant "https://github.com/gastrodon/psyduck/blob/main/stdlib/produce/constant.go"
    click Increment "https://github.com/gastrodon/psyduck/blob/main/stdlib/produce/increment.go"
    click Inspect "https://github.com/gastrodon/psyduck/blob/main/stdlib/transform/inspect.go"
    click Sprintf "https://github.com/gastrodon/psyduck/blob/main/stdlib/transform/sprintf.go"
    click Transpose "https://github.com/gastrodon/psyduck/blob/main/stdlib/transform/transpose.go"
    click Zoom "https://github.com/gastrodon/psyduck/blob/main/stdlib/transform/zoom.go"
    click Trash "https://github.com/gastrodon/psyduck/blob/main/stdlib/consume/trash.go"

    %% Styles
    classDef cli fill:#e0f7fa,stroke:#006064,color:#000
    classDef configure fill:#e8f5e9,stroke:#1b5e20,color:#000
    classDef core fill:#fff3e0,stroke:#ef6c00,color:#000
    classDef stdlib fill:#f3e5f5,stroke:#6a1b9a,color:#000
    classDef external fill:#f5f5f5,stroke:#9e9e9e,color:#000
```
