From 7b1f95dc0eb4696858cda41726f7df644829d80a Mon Sep 17 00:00:00 2001 From: Rotott <161693601+Rotott@users.noreply.github.com> Date: Thu, 2 Jul 2026 21:07:22 +0200 Subject: [PATCH 1/6] Add CMake setup, flowkit.cpp, .gitignore Add initial project scaffolding: a minimal CMakeLists.txt that defines a FlowKit executable using C++20, a simple hello-world flowkit.cpp, and a .gitignore covering common build artifacts, IDE files, logs, and temp files to keep the repo clean. (//TODO fix cmake config issues) --- .gitignore | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++ CMakeLists.txt | 11 +++++++++++ flowkit.cpp | 6 ++++++ 3 files changed, 68 insertions(+) create mode 100644 .gitignore create mode 100644 CMakeLists.txt create mode 100644 flowkit.cpp diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..fd3e6cf --- /dev/null +++ b/.gitignore @@ -0,0 +1,51 @@ +# Prerequisites +*.d + +# Compiled Object files +*.slo +*.lo +*.o +*.obj + +# Precompiled Headers +*.gch +*.pch + +# Libraries +*.la +*.a +*.lib +*.ln +*.dll +*.so +*.so.* +*.dylib + +# Executables +*.exe +*.out +*.app + +# CMake build directories +/build/ +/out/ + +# IDEs and Editors +.vscode/ +.idea/ +*.swp +*.swo +.clang-format + +# Debug symbols +*.pdb +*.dSYM/ + +# Environment / secrets +.env + +# Logs & temp files +*.log +*.tmp +*.temp +*.cache \ No newline at end of file diff --git a/CMakeLists.txt b/CMakeLists.txt new file mode 100644 index 0000000..7e8424e --- /dev/null +++ b/CMakeLists.txt @@ -0,0 +1,11 @@ +cmake_minimum_required(VERSION 3.20) + +project(FlowKit LANGUAGES CXX) + +set(CMAKE_CXX_STANDARD 20) +set(CMAKE_CXX_STANDARD_REQUIRED ON) +set(CMAKE_CXX_EXTENSIONS OFF) + +add_executable(FlowKit + flowkit.cpp +) \ No newline at end of file diff --git a/flowkit.cpp b/flowkit.cpp new file mode 100644 index 0000000..33cc891 --- /dev/null +++ b/flowkit.cpp @@ -0,0 +1,6 @@ +#include + +int main() { + std::cout << "Hello, world!" << std::endl; + return 0; +} \ No newline at end of file From bc5031ae1746a3db33bae179a39111f2979cd5df Mon Sep 17 00:00:00 2001 From: Rotott <161693601+Rotott@users.noreply.github.com> Date: Mon, 6 Jul 2026 22:55:16 +0200 Subject: [PATCH 2/6] Upd. gitignore --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index fd3e6cf..431a2db 100644 --- a/.gitignore +++ b/.gitignore @@ -29,8 +29,11 @@ # CMake build directories /build/ /out/ +CMakeSettings.json +CMakeUserPresets.json # IDEs and Editors +.vs/ .vscode/ .idea/ *.swp From c8180d548322739555dee7fa0533b132706c7dff Mon Sep 17 00:00:00 2001 From: Rotott <161693601+Rotott@users.noreply.github.com> Date: Tue, 7 Jul 2026 00:24:14 +0200 Subject: [PATCH 3/6] Add initial docs and expand README Add initial documentation files (docs/architecture.md, docs/development.md, docs/project-summary.md, docs/requirements.md) and expand README.md with a project overview, features, tech stack and links to the new docs. The added docs contain placeholder content and example diagrams; they should be updated with accurate implementation details and concrete Getting Started / usage information. --- README.md | 60 ++++++++++++++++- docs/architecture.md | 144 ++++++++++++++++++++++++++++++++++++++++ docs/development.md | 26 ++++++++ docs/project-summary.md | 9 +++ docs/requirements.md | 130 ++++++++++++++++++++++++++++++++++++ 5 files changed, 368 insertions(+), 1 deletion(-) create mode 100644 docs/architecture.md create mode 100644 docs/development.md create mode 100644 docs/project-summary.md create mode 100644 docs/requirements.md diff --git a/README.md b/README.md index 031949f..ca8c326 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,60 @@ # FlowKit -A modern C++20 workflow execution framework for building dependency-driven task pipelines. +*A modern C++20 workflow execution framework for building dependency-driven task pipelines.* + +FlowKit is a reusable workflow execution framework that enables applications to define and execute tasks connected by dependencies in a Directed Acyclic Graph (DAG). The framework is responsible for validating workflows, determining a valid execution order, and coordinating execution while remaining agnostic to the work performed by each task. + +The project serves as a portfolio piece showcasing software architecture, graph algorithms, modern C++20, and professional software engineering practices. + +--- + +## Features + +- Define workflows as dependency-driven task graphs **(TBD)** +- Automatic dependency validation **(TBD)** +- Cycle detection **(TBD)** +- Topological execution ordering **(TBD)** +- Sequential workflow execution **(TBD)** +- Shared execution context between tasks **(TBD)** + +--- + +## Tech Stack + +- **Language:** C++20 +- **Build System:** CMake +- **Testing:** GoogleTest +- **Documentation:** Mermaid +- **CI/CD: GitHub:** Actions + +--- + +## Documentation + +- [Project Summary](docs/project-summary.md) +- [Architecture](docs/architecture.md) +- [Requirements](docs/requirements.md) +- [Development](docs/development.md) + + +--- + +## Getting Started + +... + +--- + +## Example Usage + +... + +--- + +## Project Structure + +... + +--- + + + diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..92dcf35 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,144 @@ +# Architecture + +**Note this file is just a placeholder for file structure, and needs an upd with the correct info.** + +[← Back to README](../README.md) + +## Overview + +Brief description of the overall architecture and the main design goals. + +Eg: + +FlowKit is designed around a modular architecture where workflow definition, graph management, scheduling, and execution are separated into independent components. The goal is to keep the framework extensible and maintainable while ensuring that workflow execution remains independent from the tasks being executed. + +--- + +## High-Level Architecture + +Add an overview diagram here. + +Eg: + +```mermaid +flowchart TD + A[Client Application] --> B[Workflow API] + B --> C[Workflow Graph] + C --> D[Scheduler] + D --> E[Executor] + E --> F[Workflow Nodes] + E --> G[Execution Context] +``` +# Core Components + +## Workflow + +### Responsibility + +Provides the public API used by clients to construct workflows and define dependencies between tasks. + +### Responsibilities + +- Create and configure workflows +- Register workflow nodes +- Define dependencies between nodes +- Provide access to workflow execution + +--- + +## WorkflowGraph + +### Responsibility + +Manages the internal representation of workflow nodes and their relationships. + +### Responsibilities + +- Store workflow nodes +- Maintain dependency relationships +- Validate graph structure +- Detect cycles +- Support graph traversal + +--- + +## Scheduler + +### Responsibility + +Determines the order in which workflow nodes should execute. + +### Responsibilities + +- Identify executable nodes +- Resolve dependencies +- Produce a valid execution order + +--- + +## Executor + +### Responsibility + +Coordinates the execution of workflows. + +### Responsibilities + +- Execute nodes according to the schedule +- Manage execution flow +- Provide runtime context + +--- + +## Context + +### Responsibility + +Provides shared runtime data between workflow nodes. + +### Responsibilities + +- Store execution data +- Allow nodes to exchange information +- Maintain workflow state + +--- + +# Design Principles + +The architecture is guided by the following principles: + +- **Separation of concerns** + Each component has a clearly defined responsibility. + +- **Single Responsibility Principle (SRP)** + Components should have one reason to change. + +- **Composition over inheritance** + Prefer assembling functionality through composition where appropriate. + +- **Dependency Inversion Principle (DIP)** + High-level components should depend on abstractions rather than concrete implementations. + +- **Testability** + Components should be designed to support isolated testing. + +- **Extensibility** + The architecture should allow new functionality to be added without modifying existing core components. + +--- + +# Design Patterns + +The following design patterns naturally emerge from the architecture: + +| Pattern | Usage | +|---|---| +| Command | Workflow nodes represent executable tasks | +| Builder | Workflow construction API | +| Strategy | Scheduling algorithms and execution policies | +| Observer | Workflow lifecycle events | +| Dependency Injection | Shared services and runtime dependencies | + + +[← Back to README](../README.md) \ No newline at end of file diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..cbb0794 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,26 @@ +# Development + +## Development Methodology + +- Test-Driven Development (TDD) +- Feature branches +- Small, incremental commits + +## Tooling + +- C++20 +- CMake +- GoogleTest +- Mermaid +- GitHub Actions + + +## Quality Goals +- High unit test coverage +- SOLID principles +- RAII +- Separation of concerns +- Clean, maintainable APIs + + +[← Back to README](../README.md) \ No newline at end of file diff --git a/docs/project-summary.md b/docs/project-summary.md new file mode 100644 index 0000000..72625bf --- /dev/null +++ b/docs/project-summary.md @@ -0,0 +1,9 @@ +# Project Summary + +This project is a reusable workflow execution framework written in modern C++20. Rather than solving a specific business problem, it provides a generic engine for defining and executing workflows composed of tasks connected by dependencies in a Directed Acyclic Graph (DAG). Applications define their own task implementations, while the framework is responsible for validating the workflow, determining a valid execution order, and coordinating execution. + +The project was created as a portfolio piece to consolidate and demonstrate the software engineering knowledge I developed during my Bachelor's degree in Systems Development at Malmö University. It also reflects my interest in software architecture, system design, and workflow orchestration while giving me an opportunity to continue developing and maintaining my C++ skills. + +The primary goal is not to build a production-ready workflow engine, but to demonstrate sound software engineering practices through a clean, extensible architecture. The project emphasizes modern C++20, SOLID principles, graph algorithms, API design, and maintainability. It is being developed using Test-Driven Development (TDD) to encourage incremental design, comprehensive unit testing, and confidence when refactoring. + +[← Back to README](../README.md) \ No newline at end of file diff --git a/docs/requirements.md b/docs/requirements.md new file mode 100644 index 0000000..28f5dc3 --- /dev/null +++ b/docs/requirements.md @@ -0,0 +1,130 @@ + +# Requirements +**Note this file is just a placeholder for file structure, and needs an upd with the correct info.** + +[← Back to README](../README.md) + +## Project Goals + +The primary goal of FlowKit is to demonstrate the design and implementation of a reusable workflow execution framework using modern C++20. + +The project focuses on: + +- Clean software architecture +- Separation of responsibilities +- Graph-based workflow execution +- Modern C++ development practices +- Test-driven development +- Maintainable and extensible code design + +--- + +# Functional Requirements + +## Workflow Definition + +The framework shall: + +- Allow users to create and configure workflows +- Allow custom task implementations through a common interface +- Allow tasks to be connected through dependencies +- Provide an API for defining workflow structure + +--- + +## Workflow Graph Management + +The framework shall: + +- Represent workflows as a Directed Acyclic Graph (DAG) +- Store workflow nodes and their relationships +- Support dependency tracking between nodes +- Validate workflow structure before execution +- Detect circular dependencies + +--- + +## Workflow Execution + +The framework shall: + +- Execute tasks according to dependency order +- Determine a valid execution sequence using graph algorithms +- Prevent execution of tasks whose dependencies have not completed +- Coordinate execution through a dedicated execution component + +--- + +## Task System + +The framework shall: + +- Provide a base interface for executable workflow nodes +- Allow users to create custom task implementations +- Keep task logic independent from workflow orchestration + +--- + +## Execution Context + +The framework shall: + +- Provide shared runtime data between workflow nodes +- Allow tasks to exchange information during execution +- Maintain workflow execution state + +--- + +# Non-Functional Requirements + +## Architecture + +The system should: + +- Follow SOLID principles +- Maintain clear separation between components +- Favor loose coupling and high cohesion +- Use abstractions where appropriate + +--- + +## Maintainability + +The system should: + +- Have readable and well-structured code +- Use consistent coding standards +- Be easy to extend and refactor + +--- + +## Testability + +The system should: + +- Support isolated unit testing of components +- Be developed using Test-Driven Development (TDD) +- Minimize unnecessary dependencies between modules + +--- + +## Performance + +The initial implementation should: + +- Prioritize correctness and maintainability over optimization +- Avoid premature optimization +- Provide a foundation that can support future improvements + +--- + +## Technical Constraints + +The project shall: + +- Use modern C++20 features +- Use CMake as the build system +- Support automated testing +- Use version control with Git + +[← Back to README](../README.md) \ No newline at end of file From f115894a866f0d5e12d8c106a34e7c0d83e3d984 Mon Sep 17 00:00:00 2001 From: Rotott <161693601+Rotott@users.noreply.github.com> Date: Tue, 7 Jul 2026 13:04:43 +0200 Subject: [PATCH 4/6] Refactor and enhance project documentation Update README, architecture, requirements, and project summary documentation with clearer structure, detailed component descriptions, design patterns, and example usage code. Removes placeholder notes and improves overall clarity of FlowKit's design philosophy, MVP approach, and architectural decisions around DAG validation and single-threaded execution. --- README.md | 82 ++++++++++++--------- docs/architecture.md | 154 ++++++++++++++++------------------------ docs/project-summary.md | 10 ++- docs/requirements.md | 124 +++++--------------------------- 4 files changed, 132 insertions(+), 238 deletions(-) diff --git a/README.md b/README.md index ca8c326..35cfb65 100644 --- a/README.md +++ b/README.md @@ -1,60 +1,72 @@ # FlowKit -*A modern C++20 workflow execution framework for building dependency-driven task pipelines.* -FlowKit is a reusable workflow execution framework that enables applications to define and execute tasks connected by dependencies in a Directed Acyclic Graph (DAG). The framework is responsible for validating workflows, determining a valid execution order, and coordinating execution while remaining agnostic to the work performed by each task. +A modern, low-overhead C++20 workflow engine for building dependency-driven task pipelines. -The project serves as a portfolio piece showcasing software architecture, graph algorithms, modern C++20, and professional software engineering practices. +FlowKit provides a clean framework for defining tasks and connecting them into a Directed Acyclic Graph (DAG). The framework automatically handles dependency validation, cycle detection, and topological execution ordering, keeping orchestration completely separate from individual task logic. --- ## Features - -- Define workflows as dependency-driven task graphs **(TBD)** -- Automatic dependency validation **(TBD)** -- Cycle detection **(TBD)** -- Topological execution ordering **(TBD)** -- Sequential workflow execution **(TBD)** -- Shared execution context between tasks **(TBD)** +- **Fluent Graph API:** Easily declare tasks and define dependency structures. +- **Strict DAG Validation:** Automated runtime validation and cycle detection to prevent broken pipelines. +- **Topological Execution:** Resolves and runs tasks sequentially based on mathematical dependency order. +- **Modern C++ Core:** Employs RAII, clean type abstractions, and standard library graph algorithms. --- -## Tech Stack +## Architecture & Roadmap +FlowKit is explicitly designed around separation of concerns to support clean software engineering metrics. It is currently implemented as a highly deterministic, single-threaded execution engine (MVP). The clean separation between the `WorkflowGraph` and the `Executor` ensures that a concurrent, thread-pool-based executor can be integrated in the future without modifying user-defined tasks. -- **Language:** C++20 -- **Build System:** CMake -- **Testing:** GoogleTest -- **Documentation:** Mermaid -- **CI/CD: GitHub:** Actions - ---- - -## Documentation - -- [Project Summary](docs/project-summary.md) -- [Architecture](docs/architecture.md) -- [Requirements](docs/requirements.md) -- [Development](docs/development.md) - +For a deep dive into design choices, see the links below: +- [Project Summary](docs/project-summary.md) +- [Requirements Specification](docs/requirements.md) +- [Architecture & Components](docs/architecture.md) +- [Development & Quality Goals](docs/development.md) --- -## Getting Started - -... +## Tech Stack +- **Language:** C++20 +- **Build System:** CMake +- **Testing:** GoogleTest +- **Documentation Diagrams:** Mermaid --- -## Example Usage +## Example Usage **(TBD)** -... +```cpp +#include +#include ---- +// Define a custom task by inheriting from the base Task class +class DownloadDataTask : public flowkit::Task { +public: + bool execute() override { + std::cout << "Downloading raw assets...\n"; + return true; // Return success + } +}; -## Project Structure +int main() { + flowkit::WorkflowGraph graph; -... + // Register tasks + graph.add_task("download", std::make_unique()); + graph.add_task("process", []() { + std::cout << "Processing assets...\n"; + return true; + }); ---- + // Define dependencies (Process depends on Download) + graph.add_dependency("download", "process"); + // Execute the workflow + flowkit::Executor executor; + bool success = executor.run(graph); + return success ? 0 : 1; +} +``` +**//TODO add context changing between nodes** \ No newline at end of file diff --git a/docs/architecture.md b/docs/architecture.md index 92dcf35..e000601 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,144 +1,112 @@ # Architecture -**Note this file is just a placeholder for file structure, and needs an upd with the correct info.** - -[← Back to README](../README.md) - ## Overview -Brief description of the overall architecture and the main design goals. - -Eg: - -FlowKit is designed around a modular architecture where workflow definition, graph management, scheduling, and execution are separated into independent components. The goal is to keep the framework extensible and maintainable while ensuring that workflow execution remains independent from the tasks being executed. +FlowKit uses a modular architecture that separates workflow definition from workflow execution. The execution engine is currently single-threaded, while the design preserves the structural guarantees necessary to support a future multi-threaded execution model with minimal architectural changes. --- -## High-Level Architecture - -Add an overview diagram here. - -Eg: +## High-Level Component Design ```mermaid flowchart TD - A[Client Application] --> B[Workflow API] - B --> C[Workflow Graph] - C --> D[Scheduler] - D --> E[Executor] - E --> F[Workflow Nodes] - E --> G[Execution Context] + A[Client Application] -->|Defines Tasks & Edges| B[WorkflowGraph] + B -->|Passed to| C[Executor] + C -->|1. Validates & Sorts| C[Executor] + C -->|2. Runs Sequentially| D[Task Nodes] ``` -# Core Components - -## Workflow - -### Responsibility - -Provides the public API used by clients to construct workflows and define dependencies between tasks. - -### Responsibilities - -- Create and configure workflows -- Register workflow nodes -- Define dependencies between nodes -- Provide access to workflow execution --- -## WorkflowGraph +## Core Components -### Responsibility +### 1. WorkflowGraph -Manages the internal representation of workflow nodes and their relationships. +**Responsibility** -### Responsibilities +- Represents the workflow as a Directed Acyclic Graph (DAG). +- Stores task nodes. +- Maintains directed dependency edges between tasks. -- Store workflow nodes -- Maintain dependency relationships -- Validate graph structure -- Detect cycles -- Support graph traversal +**Validation** ---- - -## Scheduler - -### Responsibility +Before execution, the graph validates its structure by performing cycle detection using either: +**(TBD:)** +- Depth-First Search (DFS) +- Kahn's Algorithm +- (Or other) -Determines the order in which workflow nodes should execute. + Execution is only allowed if the graph is a valid DAG. -### Responsibilities +--- -- Identify executable nodes -- Resolve dependencies -- Produce a valid execution order +### 2. Task (Interface) ---- +**Responsibility** -## Executor +Defines the behavioral contract for executable work units. -### Responsibility +**Characteristics** -Coordinates the execution of workflows. +- Exposes a single execution method: -### Responsibilities +```c++ +execute() +``` -- Execute nodes according to the schedule -- Manage execution flow -- Provide runtime context +- Completely independent from graph mechanics. +- Tasks have no knowledge of neighboring nodes. +- Easily extensible for custom task implementations. --- -## Context +### 3. Executor -### Responsibility +**Responsibility** -Provides shared runtime data between workflow nodes. +Coordinates the complete workflow lifecycle. -### Responsibilities +**Execution Steps** -- Store execution data -- Allow nodes to exchange information -- Maintain workflow state +1. Accepts a validated `WorkflowGraph`. +2. Performs topological sorting. +3. Executes tasks sequentially. +4. Tracks execution state. +5. Reports execution failures when encountered. ---- +The executor owns execution logic while the graph remains a pure structural model. -# Design Principles +--- -The architecture is guided by the following principles: +## Design Patterns -- **Separation of concerns** - Each component has a clearly defined responsibility. +| Pattern | Usage | Benefit | +|----------|-------|---------| +| Command | Task abstraction | Encapsulates executable actions behind a consistent interface without exposing framework internals. | +| Builder / Fluent API | Workflow construction | Provides a readable and expressive API for defining workflows and linking task dependencies. | -- **Single Responsibility Principle (SRP)** - Components should have one reason to change. +--- -- **Composition over inheritance** - Prefer assembling functionality through composition where appropriate. +## Architectural Decision: Shared Context -- **Dependency Inversion Principle (DIP)** - High-level components should depend on abstractions rather than concrete implementations. +The framework intentionally excludes a global, untyped shared context. -- **Testability** - Components should be designed to support isolated testing. +### Rationale -- **Extensibility** - The architecture should allow new functionality to be added without modifying existing core components. +Global mutable state introduces several long-term issues: ---- +- Weakens DAG guarantees. +- Couples otherwise independent tasks. +- Creates data-race risks when introducing parallel execution. +- Makes workflows harder to reason about and test. -# Design Patterns +### Preferred Approach -The following design patterns naturally emerge from the architecture: +Data should flow explicitly through: -| Pattern | Usage | -|---|---| -| Command | Workflow nodes represent executable tasks | -| Builder | Workflow construction API | -| Strategy | Scheduling algorithms and execution policies | -| Observer | Workflow lifecycle events | -| Dependency Injection | Shared services and runtime dependencies | +- Type-safe task inputs and outputs. +- Localized token or message passing between tasks. +This approach keeps task dependencies explicit, improves maintainability, and allows the execution engine to evolve toward safe concurrent execution without redesigning the core architecture. [← Back to README](../README.md) \ No newline at end of file diff --git a/docs/project-summary.md b/docs/project-summary.md index 72625bf..d81be82 100644 --- a/docs/project-summary.md +++ b/docs/project-summary.md @@ -1,9 +1,13 @@ # Project Summary -This project is a reusable workflow execution framework written in modern C++20. Rather than solving a specific business problem, it provides a generic engine for defining and executing workflows composed of tasks connected by dependencies in a Directed Acyclic Graph (DAG). Applications define their own task implementations, while the framework is responsible for validating the workflow, determining a valid execution order, and coordinating execution. +This project is a lightweight, high-performance workflow execution engine written in modern C++20. It provides a generic framework for defining and executing tasks connected by dependencies in a Directed Acyclic Graph (DAG). Applications define their own task implementations, while FlowKit validates the graph structure, determines a valid execution order, and manages execution. -The project was created as a portfolio piece to consolidate and demonstrate the software engineering knowledge I developed during my Bachelor's degree in Systems Development at Malmö University. It also reflects my interest in software architecture, system design, and workflow orchestration while giving me an opportunity to continue developing and maintaining my C++ skills. +The project was created as a portfolio piece to bridge the gap between traditional enterprise object-oriented design and modern, low-overhead C++ paradigms. It demonstrates software architecture, graph algorithms, and clean system design developed during my Bachelor's degree in Systems Development at Malmö University. -The primary goal is not to build a production-ready workflow engine, but to demonstrate sound software engineering practices through a clean, extensible architecture. The project emphasizes modern C++20, SOLID principles, graph algorithms, API design, and maintainability. It is being developed using Test-Driven Development (TDD) to encourage incremental design, comprehensive unit testing, and confidence when refactoring. +### Architectural Philosophy +Rather than over-engineering the engine with heavy enterprise runtime abstractions, FlowKit focuses on C++ idiomatic practices: +- **Value Semantics & RAII:** Efficient memory management without relying on unnecessary heap allocation or pointer chasing. +- **Compile-Time Safety over Runtime Guessing:** Maximizing type safety and leveraging modern C++ structures to prevent runtime crashes. +- **Incremental Scaling:** Designed as a single-threaded Minimum Viable Product (MVP) with structural provisions to seamlessly transition to a multi-threaded execution pool. [← Back to README](../README.md) \ No newline at end of file diff --git a/docs/requirements.md b/docs/requirements.md index 28f5dc3..b602067 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -1,130 +1,40 @@ - -# Requirements -**Note this file is just a placeholder for file structure, and needs an upd with the correct info.** - -[← Back to README](../README.md) +# Requirements ## Project Goals - -The primary goal of FlowKit is to demonstrate the design and implementation of a reusable workflow execution framework using modern C++20. - -The project focuses on: - -- Clean software architecture -- Separation of responsibilities -- Graph-based workflow execution -- Modern C++ development practices -- Test-driven development -- Maintainable and extensible code design +The primary goal of FlowKit is to showcase modern C++20 development practices through a clean, highly cohesive workflow engine. --- # Functional Requirements -## Workflow Definition - -The framework shall: - -- Allow users to create and configure workflows -- Allow custom task implementations through a common interface -- Allow tasks to be connected through dependencies -- Provide an API for defining workflow structure - ---- - -## Workflow Graph Management - +## Workflow Definition & Graph Management The framework shall: - -- Represent workflows as a Directed Acyclic Graph (DAG) -- Store workflow nodes and their relationships -- Support dependency tracking between nodes -- Validate workflow structure before execution -- Detect circular dependencies - ---- +- Allow users to define tasks (as nodes) and construct them into workflows as Directed Acyclic Graphs (DAGs) using a clean programmatic API. +- Validate the graph structure prior to execution, explicitly detecting and rejecting circular dependencies. +- Track structural dependencies between discrete task nodes. ## Workflow Execution - The framework shall: - -- Execute tasks according to dependency order -- Determine a valid execution sequence using graph algorithms -- Prevent execution of tasks whose dependencies have not completed -- Coordinate execution through a dedicated execution component - ---- +- Perform a topological sort to resolve a valid sequential execution order for the graph. +- Execute tasks strictly according to dependency order, ensuring no task runs until its dependencies complete. +- Provide runtime state feedback (e.g., Success, Failure) upon completion of execution. ## Task System - The framework shall: - -- Provide a base interface for executable workflow nodes -- Allow users to create custom task implementations -- Keep task logic independent from workflow orchestration - ---- - -## Execution Context - -The framework shall: - -- Provide shared runtime data between workflow nodes -- Allow tasks to exchange information during execution -- Maintain workflow execution state +- Provide a clear interface/base-class for custom executable tasks. +- Isolate task-specific execution logic entirely from graph management and orchestration logic. --- # Non-Functional Requirements -## Architecture - -The system should: - -- Follow SOLID principles -- Maintain clear separation between components -- Favor loose coupling and high cohesion -- Use abstractions where appropriate - ---- - -## Maintainability - -The system should: - -- Have readable and well-structured code -- Use consistent coding standards -- Be easy to extend and refactor - ---- +## Architecture & Maintainability +- **High Cohesion:** Keep graph storage, validation, and execution mechanisms strictly separated. +- **Low Overhead:** Avoid unnecessary virtual method dispatch or heavy design pattern abstractions where standard library mechanisms (`std::function`, algorithms) suffice. +- **Modern C++20 Constraints:** Leverage C++20 features (e.g., standard library concepts, improved containers) using CMake as the build system. ## Testability - -The system should: - -- Support isolated unit testing of components -- Be developed using Test-Driven Development (TDD) -- Minimize unnecessary dependencies between modules - ---- - -## Performance - -The initial implementation should: - -- Prioritize correctness and maintainability over optimization -- Avoid premature optimization -- Provide a foundation that can support future improvements - ---- - -## Technical Constraints - -The project shall: - -- Use modern C++20 features -- Use CMake as the build system -- Support automated testing -- Use version control with Git +- Accommodate comprehensive unit testing via GoogleTest. +- Built using Test-Driven Development (TDD) to ensure code reliability and structural flexibility for future performance optimizations. [← Back to README](../README.md) \ No newline at end of file From 06e370cb9557a4d26a111b21f05978c3c8bb2456 Mon Sep 17 00:00:00 2001 From: Rotott <161693601+Rotott@users.noreply.github.com> Date: Tue, 7 Jul 2026 16:12:02 +0200 Subject: [PATCH 5/6] Add sequence diagram and rendering fix Add a high-level flow sequence diagram showcasing the lifecycle of a workflow. Update the flowchart so it renders correctly. --- docs/architecture.md | 52 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 50 insertions(+), 2 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index e000601..ac29617 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -12,8 +12,8 @@ FlowKit uses a modular architecture that separates workflow definition from work flowchart TD A[Client Application] -->|Defines Tasks & Edges| B[WorkflowGraph] B -->|Passed to| C[Executor] - C -->|1. Validates & Sorts| C[Executor] - C -->|2. Runs Sequentially| D[Task Nodes] + C -->|Step 1: Validate & Sort| C + C -->|Step 2: Run Sequentially| D[Task Nodes] ``` --- @@ -78,6 +78,54 @@ The executor owns execution logic while the graph remains a pure structural mode --- +## System Execution Flow + +The following sequence diagram outlines the entire lifecycle of a workflow—from initialization by the client application to structural graph validation, topological sorting, and sequential task execution. + +### High-Level Flow +```mermaid +sequenceDiagram + autonumber + actor Client as User / Client Application + participant Graph as WorkflowGraph + participant Exec as Executor + participant Task as Task Nodes + + Client->>Graph: 1. Define tasks & edges + Client->>Exec: 2. Invoke run(graph) + + activate Exec + Exec->>Graph: 3. Perform structural validation + + alt Graph contains a cycle + Graph-->>Exec: Validation failed + Exec-->>Client: Return validation error + + else Graph is a valid DAG + Graph-->>Exec: Validation passed + + Exec->>Exec: 4. Perform topological sort + + loop For each sorted task + Exec->>Task: 5. execute() + activate Task + Task-->>Exec: 6. Success/Failure + deactivate Task + + alt Task failed + Exec->>Exec: Halt execution + Exec-->>Client: Return failure state + end + end + + Exec-->>Client: 7. Return success state + end + + deactivate Exec + + ``` +--- + ## Design Patterns | Pattern | Usage | Benefit | From 93f67b57cc9da0556bdcab54b1cb401b84248fab Mon Sep 17 00:00:00 2001 From: Rotott <161693601+Rotott@users.noreply.github.com> Date: Tue, 7 Jul 2026 16:45:29 +0200 Subject: [PATCH 6/6] Add workflow Add first draft for the auto testing workflow --- .github/workflows/ci.yml | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 .github/workflows/ci.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..3bfc494 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,32 @@ +name: FlowKit CI, tests + +on: + push: + branches: [ main, master ] + pull_request: + branches: [ main, master ] + +jobs: + build-and-test: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Install dependencies + run: | + sudo apt-get update + sudo apt-get install -y cmake g++-11 + + - name: Configure CMake + run: | + cmake -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=g++-11 + + - name: Build project + run: cmake --build build --config Release + + - name: Run tests suite + run: | + cd build + ctest --output-on-failure \ No newline at end of file