How couzic/verdux works
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).