# linkdlab/funcnodes_core architecture

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

- Interactive diagram: https://gitdiagram.com/linkdlab/funcnodes_core
- Repository: https://github.com/linkdlab/funcnodes_core

## Overview

##### Project Type and Purpose
- This is a Python core‐library package (“funcnodes_core”) designed to support the FuncNodes framework.
- It provides the building blocks (nodes, graphs, event management, I/O, plugins, utilities) that let users define, link, and execute computational nodes in a DAG (directed acyclic graph).

##### High-Level Components
a. Decorator & NodeMaker
- funcnodes_core/decorator: Provides @node decorators.
- nodemaker.py: Turns decorated Python functions into Node objects.

b. Node & Graph Management
- node.py / nodeclass: Core Node class definitions and mixins.
- graph.py: Graph object representing a collection of connected nodes.

c. Data & I/O
- data.py / datapath.py: Abstractions for input/output data and filesystem paths.
- io.py: Read/write nodes, serialization formats.
- utils/serialization.py: Helpers to serialize node states and graphs.

d. Execution & Eventing
- eventmanager.py: Central event bus for node lifecycle events.
- triggerstack.py: Manages triggering and scheduling of node executions.
- utils/testing.py: Mocks or helpers for injecting events during tests.

e. Libraries & Plugins
- lib/lib.py, libfinder.py, libparser.py: Dynamic library discovery and parsing.
- utils/plugins*.py: Plugin registration, plugin–type definitions.

f. Configuration & Setup
- config.py: Global settings.
- _setup.py: Installation and package metadata.
- _logging.py: Centralized logging configuration.

g. Utilities
- utils/functions.py, nodeutils.py, files.py, etc.: Cross‐cutting helper functions.

##### Relationships & Interactions
- User’s Python function → @node decorator → registered in NodeMaker
- NodeMaker → produces Node instances → registered into NodeSpace
- NodeSpace → constructs Graph with Node objects + edges
- Graph execution → EventManager emits lifecycle events → TriggerStack schedules node computations
- Data modules feed input/output data into nodes; IO modules persist graph and results.
- Plugin system extends Node types or data readers; lib modules discover third‐party libraries.
- Utils and logging are cross‐cutting services used by all components.

##### Architectural Patterns & Principles
- Modular design: clear separation of concerns (declaration, graph, execution, I/O, plugins).
- Event-driven execution: EventManager and TriggerStack implement reactive scheduling.
- Plugin architecture: dynamic discovery/extension points via libfinder and utils/plugins.
- Testability: testing mocks and fixtures under tests/ plus pytest integration.

##### Detail Level
- Every major module grouping—do not break down into every file but list representative files.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Consumer
    subgraph "Consumer"
        UserApp["User Application / CLI"]:::external
    end

    %% Declaration Layer
    subgraph "Decorator & NodeMaker" 
        Decorator["Decorator Layer\n(funcnodes_core/decorator/)"]:::declaration
        NodeMaker["NodeMaker\nnodemaker.py"]:::declaration
    end

    %% Node & Graph Management
    subgraph "Node & Graph Management"
        NodeDefs["Node Definitions\nnode.py"]:::declaration
        NodeSpace["NodeSpace\nnodespace.py"]:::declaration
        Graph["Graph Builder\ngraph.py"]:::declaration
    end

    %% Execution Engine
    subgraph "Execution Engine"
        EventManager["EventManager\neventmanager.py"]:::execution
        TriggerStack["TriggerStack\ntriggerstack.py"]:::execution
    end

    %% Data & I/O Layer
    subgraph "Data & I/O Layer"
        DataAbstr["Data Abstractions\ndata.py, datapath.py"]:::io
        IO["I/O Module\nio.py"]:::io
        Serialization["Serialization Helpers\nutils/serialization.py"]:::io
    end

    %% Plugins & Libraries
    subgraph "Plugins & Library Loader"
        Lib["Library Loader\nlib/lib.py"]:::plugin
        LibFinder["Library Finder\nlib/libfinder.py"]:::plugin
        LibParser["Library Parser\nlib/libparser.py"]:::plugin
        PluginsReg["Plugin Registration\nutils/plugins.py"]:::plugin
        PluginsType["Plugin Types\nutils/plugins_types.py"]:::plugin
    end

    %% Utilities & Cross-cutting
    subgraph "Utilities & Cross-cutting"
        Config["Config\nconfig.py"]:::crosscut
        Logging["Logging\n_logging.py"]:::crosscut
        UtilsFunc["Functions\nutils/functions.py"]:::util
        UtilsFiles["Files\nutils/files.py"]:::util
        UtilsNode["Node Utils\nutils/nodeutils.py"]:::util
        UtilsData["Data Utils\nutils/data.py"]:::util
        Deprec["Deprecations\nutils/deprecations.py"]:::util
    end

    %% Test Suite & CI
    subgraph "Test Suite"
        Testing["Testing Utils\ntesting.py"]:::test
        CI["CI / GitHub Actions"]:::external
    end

    %% Connections
    UserApp -->|"uses decorator"| Decorator
    Decorator -->|"decorates functions"| NodeMaker
    NodeMaker -->|"creates Node instances"| NodeDefs
    NodeDefs -->|"registers in"| NodeSpace
    NodeSpace -->|"builds graph"| Graph
    Graph -->|"executes via"| EventManager
    EventManager -->|"emits events to"| TriggerStack
    TriggerStack -->|"schedules computations on"| NodeDefs

    EventManager -->|"feeds"| DataAbstr
    TriggerStack -->|"invokes"| IO
    IO -->|"read/write data"| DataAbstr

    PluginsReg -->|"extends"| NodeMaker
    LibFinder -->|"discovers plugins for"| PluginsReg
    LibParser -->|"parses libraries for"| PluginsReg
    Lib -->|"provides libraries to"| NodeMaker

    Config --> Decorator
    Config --> NodeMaker
    Config --> NodeDefs
    Config --> NodeSpace
    Config --> EventManager
    Config --> IO
    Config --> PluginsReg

    Logging --> Decorator
    Logging --> NodeMaker
    Logging --> NodeDefs
    Logging --> NodeSpace
    Logging --> EventManager
    Logging --> IO
    Logging --> PluginsReg

    Testing --> Decorator
    Testing --> NodeMaker
    Testing --> NodeDefs
    Testing --> NodeSpace
    Testing --> EventManager
    Testing --> IO
    Testing --> PluginsReg

    CI --> Testing

    %% Click Events
    click Decorator "https://github.com/linkdlab/funcnodes_core/tree/main/src/funcnodes_core/decorator/"
    click NodeMaker "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/nodemaker.py"
    click NodeDefs "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/node.py"
    click NodeSpace "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/nodespace.py"
    click Graph "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/graph.py"
    click DataAbstr "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/data.py"
    click DataAbstr "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/datapath.py"
    click IO "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/io.py"
    click Serialization "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/utils/serialization.py"
    click EventManager "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/eventmanager.py"
    click TriggerStack "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/triggerstack.py"
    click Testing "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/testing.py"
    click Lib "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/lib/lib.py"
    click LibFinder "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/lib/libfinder.py"
    click LibParser "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/lib/libparser.py"
    click PluginsReg "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/utils/plugins.py"
    click PluginsType "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/utils/plugins_types.py"
    click Config "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/config.py"
    click Logging "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/_logging.py"
    click UtilsFunc "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/utils/functions.py"
    click UtilsFiles "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/utils/files.py"
    click UtilsNode "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/utils/nodeutils.py"
    click UtilsData "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/utils/data.py"
    click Deprec "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/utils/deprecations.py"
    click NodeMaker "https://github.com/linkdlab/funcnodes_core/blob/main/src/funcnodes_core/nodemaker.py"

    %% Styles
    classDef declaration fill:#D0E6FF,stroke:#4D8ACE,color:#000;
    classDef execution fill:#D4F7DD,stroke:#2E8B57,color:#000;
    classDef io fill:#FFE8B0,stroke:#E09100,color:#000;
    classDef plugin fill:#F0D0FF,stroke:#A64DFF,color:#000;
    classDef util fill:#E2E2E2,stroke:#888,color:#000;
    classDef crosscut fill:#F5F5F5,stroke:#666,color:#000;
    classDef external fill:#FFFFFF,stroke:#000,color:#000,stroke-dasharray: 5 5;
    classDef test fill:#FFD1D1,stroke:#D32F2F,color:#000;
```
