# couzic/verdux architecture

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

- Interactive diagram: https://gitdiagram.com/couzic/verdux
- Repository: https://github.com/couzic/verdux

## Overview

##### Main Components of the System

- Configuration Module (located in src/config):
- Contains files such as VertexConfig, DependencyProviders, and builders.
- Responsible for setting up vertex configurations and dependency injection.
- Acts as the entry point to initialize the graph’s structure.

- Graph Module (located in src/graph):
- Manages the construction and core info of the graph (Graph.ts, GraphCoreInfo.ts).
- Provides functionality to create the vertex graph and compute graph core details.

- Vertex Module (located in src/vertex):
- Implements the basic vertex data structure (Vertex.ts, VertexData.ts, VertexInstance.ts).
- Defines the identity and status of each vertex.

- Operations Module (located in src/operation):
- Contains the functions and tests for various vertex interactions such as reactions, loading, and computed fields (e.g., reaction$, computeFromFields, fieldsReaction).
- Handles asynchronous operations, side effects, and data flow between vertices.

- Run Module (located in src/run):
- Orchestrates the execution of the graph (GraphRun, RunData, and VertexRun).

- State Module (located in src/state):
- Manages Redux-compatible state definitions such as VertexState, VertexReduxState, and loadable states.
- Contains utilities to compare and pick fields, ensuring maximum type safety.

- DevTools Module (located in src/devtools):
- Offers support for debugging and visualization (e.g., SerializedGraphRunData, SerializedGraphStructure, VerduxDevTools).
- This is especially useful for understanding the live state and structure during runs.

- Utility Module (located in src/util):
- Provides helper functions (FIFO, shallowEquals, IsPlainObject, etc.) that are used across the system.

##### Relationships and Interactions

- Initialization Phase:
- The Configuration Module prepares all vertex definitions and dependency providers.
- This configuration is then passed to the Graph Module to construct the directed acyclic graph.

- Execution Flow:
- The Graph Module provides the core graph structure that the Run Module executes.
- The Operations Module defines the asynchronous computations, reactions, and side effects that occur on the vertices.
- These operations update or interact with the State Module to maintain up-to-date application state.

- Data Flow and State Management:
- There is a clear flow from initialization (via configuration) to graph construction and execution.
- Operations act as bridges between the Graph and State modules, using RxJS streams to propagate changes.
- The Redux integration points (supported by Redux Toolkit) lie in the State module, ensuring that external UI components receive changes.

- Feedback and Debugging:
- DevTools provide visualization hooks and serialization of both the graph structure and runtime data.
- This assists in debugging complex asynchronous flows and state updates.

##### Architectural Patterns

- Modular and Layered Architecture:
- Each module (configuration, graph, vertex, operations, run, state) encapsulates a distinct concern.

- Reactive Programming:
- The heavy use of RxJS in asynchronous operations and reactions.

- Integration with Redux:
- While abstracting and enhancing standard Redux functionality, the project leverages Redux’s pure functions and the Redux Toolkit as part of its state management.

- Directed Acyclic Graph as a Central Model:
- The entire system is built around the graph, with vertices as self-contained and reactive units.

##### Recommendations

- From Configuration to Graph (configuring vertices).
- From Graph to Operations (triggering asynchronous actions).
- From Operations to Run (executing vertex behavior).
- From Run into State (maintaining the computed state).
- From State back to external UI components (Redux integration).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Initialization Layer
    subgraph "Initialization Layer"
        CONFIG["Configuration (src/config)"]:::core
    end

    %% Graph Construction Layer
    subgraph "Graph Construction"
        GRAPH["Graph (src/graph)"]:::core
        VERTEX["Vertex (src/vertex)"]:::core
    end

    %% Reactive Operations Layer
    subgraph "Reactive Operations"
        OPERATIONS["Operations (src/operation)"]:::core
        RUN["Run (src/run)"]:::core
    end

    %% State Management Layer
    subgraph "State Management"
        STATE["State (src/state)"]:::state
        UI["Redux Integration (External UI)"]:::external
    end

    %% Support Layer
    subgraph "Support"
        DEVTOOLS["DevTools (src/devtools)"]:::support
        UTIL["Utility (src/util)"]:::support
    end

    %% Flow Connections
    CONFIG -->|"configures"| GRAPH
    GRAPH -->|"composes"| VERTEX
    VERTEX -->|"triggersReactiveFlows"| OPERATIONS
    GRAPH -->|"feedsExecution"| RUN
    OPERATIONS -->|"executes"| RUN
    OPERATIONS -->|"updatesState"| STATE
    RUN -->|"transforms"| STATE
    STATE -->|"ReduxUpdate"| UI
    DEVTOOLS -->|"monitors"| GRAPH
    DEVTOOLS -->|"debugs"| STATE
    UTIL -->|"helpers"| OPERATIONS

    %% Click Events
    click CONFIG "https://github.com/couzic/verdux/tree/master/src/config"
    click GRAPH "https://github.com/couzic/verdux/tree/master/src/graph"
    click VERTEX "https://github.com/couzic/verdux/tree/master/src/vertex"
    click OPERATIONS "https://github.com/couzic/verdux/tree/master/src/operation"
    click RUN "https://github.com/couzic/verdux/tree/master/src/run"
    click STATE "https://github.com/couzic/verdux/tree/master/src/state"
    click DEVTOOLS "https://github.com/couzic/verdux/tree/master/src/devtools"
    click UTIL "https://github.com/couzic/verdux/tree/master/src/util"

    %% Styles
    classDef core fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef state fill:#A3E4D7,stroke:#333,stroke-width:2px;
    classDef support fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#333,stroke-width:2px;
```
