# chunelfeng/cgraph architecture

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

- Interactive diagram: https://gitdiagram.com/chunelfeng/cgraph
- Repository: https://github.com/chunelfeng/cgraph

## Overview

##### Main Components
- Core Execution Engine:
- Pipeline Management: Represented by “GPipeline”, “GPipelineFactory”, and pipeline registration code (shown in both C++ and Python demos).
- Graph Controllers: Modules under src/GraphCtrl (including GraphElement, GraphNode, GraphAspect, GraphDaemon, GraphEvent, GraphParam, GraphPipeline, GraphStage, and utility classes around messaging and optimization).
- Domain and Utility Modules: The DomainCtrl folder (for domain-specific logic) and multiple utilities under src/UtilsCtrl for containers, thread pools, timers, locks, random functions, etc.
- Node Abstractions:
- GNode implementations appear throughout “tutorial” and “example” folders, as well as within the src modules.
- Grouping and aspect functionalities that allow extending the node’s behavior.
- Concurrency and Scheduling:
- The thread pool implementation (in src/UtilsCtrl/ThreadPool) which includes features like work stealing, task groups, and metrics.
- External Interfaces:
- Python API: The python folder (with PyCGraph wrapper files, setup.py, and sample tutorials) and the wrapper folder for pybind11 integration.
- Build and Test Infrastructure:
- The presence of CMakeLists.txt, xmake.lua, WORKSPACE (for Bazel), and continuous integration scripts (github/workflows) means that the build configuration, tests (in test folder), and packaging are integral parts of the project.
- Documentation and Examples:
- Detailed tutorials and examples, plus extensive documentations under doc and tutorial directories, provide insights into system usage and typical execution flows.

##### Relationships and Interactions
- The user (or upper application layer) creates a “pipeline” using the pipeline factory, registers nodes (subclassing GNode) and sets up dependencies.
- The pipeline (graph controller) then orchestrates the execution of the node graph:
- It consults the dependency definitions to schedule tasks.
- Uses internal thread pool utilities (under UtilsCtrl/ThreadPool) to execute non-dependent nodes concurrently.
- Injects additional functionality through aspects (GAspect), adapters (GAdapter) or conditions (GCondition) as needed.
- Support modules (like timers, distance calculators, and singletons) provide auxiliary services to enable finer control and performance tuning.
- The Python binding layer sits as an adapter between Python caller and the underlying C++ engine, making use of the wrapper interface.

##### Architectural Patterns and Design Principles
- Modular design: The architecture is decomposed into several modules (graph control, utilities, domain, wrapper) which are clearly organized by directory. This separation is key to extensibility.
- Dependency injection & inversion: Users customize behavior by overriding run() in node subclasses and by injecting additional behavior (e.g., aspects).
- Pipeline/Graph scheduling: Emphasizes scheduling rules based on dependencies (a DAG execution) similar in spirit to modern taskflow systems.
- Concurrency: Uses thread pooling, asynchronous execution, and work stealing strategies to optimize performance.

##### Relevant Technologies and Frameworks
- C++11 Standard Library (no external dependencies)
- Python via pybind11 (for the Python interface)
- CMake, Ninja, Bazel, and xmake for build automation
- GitHub Actions and CodeQL for CI and static analysis.

##### Additional Detail Suggestions
- For each major component, include a brief note on its purpose (e.g., “GPipeline – orchestrates node execution and dependency management”).
- Showing sample flow: how a simple graph (as shown in the demo) progresses from the initial “nodeA” to parallel execution and then sequential dependency resolution.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interfaces
    UC("User Code"):::external
    PyAPI("Python API Binding"):::external

    %% Core Execution Engine
    subgraph "Core Execution Engine"
        GPF("GPipelineFactory<br/>(Pipeline Management)"):::engine
        GP("GPipeline<br/>(Execution Engine)"):::engine
        GC("Graph Controllers<br/>(GraphElement, GraphAspect, etc.)"):::engine
        NA("Node Abstractions"):::engine
        CppNodes("C++ Node Definitions"):::engine
        Tuts("Tutorial Nodes"):::engine
        PyTuts("Python Tutorial Nodes"):::engine
    end

    %% Concurrency and Scheduling
    subgraph "Concurrency & Scheduling"
        TP("Thread Pool"):::engine
    end

    %% Domain and Utility Modules
    subgraph "Domain & Utility Modules"
        DM("Domain Modules"):::utility
        UM("Utility Modules"):::utility
    end

    %% Build, Test and Documentation
    subgraph "Build, Test & Documentation"
        BT("Build & Test Infrastructure"):::build
        DT("Documentation & Tutorials"):::build
    end

    %% Connections for External Interfaces and Core Engine
    UC -->|"creates"| GPF
    PyAPI -->|"calls"| GPF

    %% Core Execution Flow
    GPF -->|"creates"| GP
    GP -->|"manages"| GC
    GC -->|"executes"| NA
    NA -->|"includes"| CppNodes
    NA -->|"includes"| Tuts
    NA -->|"includes"| PyTuts

    %% Concurrency and Utility Connections
    GC -->|"submitsTasks"| TP
    GC -->|"utilizes"| DM
    GC -->|"utilizes"| UM

    %% Optional relation from User Code to Build/Documentation
    UC -.->|"validatedBy"| BT
    UC -.->|"guides"| DT

    %% Click Events
    click GPF "https://github.com/chunelfeng/cgraph/blob/main/src/GraphCtrl/GraphPipeline/GPipelineFactory.cpp"
    click GP "https://github.com/chunelfeng/cgraph/blob/main/src/GraphCtrl/GraphPipeline/GPipeline.cpp"
    click GC "https://github.com/chunelfeng/cgraph/tree/main/src/GraphCtrl/"
    click CppNodes "https://github.com/chunelfeng/cgraph/blob/main/src/GraphCtrl/GraphElement/GNode/GNode.cpp"
    click Tuts "https://github.com/chunelfeng/cgraph/tree/main/tutorial/MyGNode"
    click PyTuts "https://github.com/chunelfeng/cgraph/tree/main/python/tutorial/MyGNode"
    click TP "https://github.com/chunelfeng/cgraph/tree/main/src/UtilsCtrl/ThreadPool"
    click DM "https://github.com/chunelfeng/cgraph/tree/main/src/DomainCtrl"
    click UM "https://github.com/chunelfeng/cgraph/tree/main/src/UtilsCtrl"
    click PyAPI "https://github.com/chunelfeng/cgraph/tree/main/python/"
    click BT "https://github.com/chunelfeng/cgraph/blob/main/CMakeLists.txt"
    click DT "https://github.com/chunelfeng/cgraph/tree/main/doc/"

    %% Styles
    classDef external fill:#ffdead,stroke:#000,stroke-width:2px;
    classDef engine fill:#98fb98,stroke:#000,stroke-width:2px;
    classDef utility fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef build fill:#ffb6c1,stroke:#000,stroke-width:2px;
```
