Add version 1.2.x documentation #140

Author: ziagham

docusaurus.config.ts

@@ -42,9 +42,15 @@ const config: Config = {
           showLastUpdateTime: true,
           showLastUpdateAuthor: false,
           includeCurrentVersion: true,
+          lastVersion: 'current',
           versions: {
+            '1.2.x': {
+              label: '1.2.x',
+              banner: 'none',
+            },
             current: {
-              label: 'Version: 1.2.x',
+              label: '1.3.x (Latest)',
+              path: '/',
             },
           },
         },

versioned_docs/version-1.2.x/concepts/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Concepts",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "slug": "/concepts",
+    "description": "Learn the fundamental concepts behind FlowSynx, including architecture, data flow, and best practices."
+  }
+}

versioned_docs/version-1.2.x/concepts/dependencies-execution-order.mdx

@@ -0,0 +1,143 @@
+---
+sidebar_position: 3
+description: Understanding how FlowSynx manages task dependencies and execution order using DAG-based scheduling to ensure reliable, predictable, and optimized workflow execution.
+---
+
+# Dependencies & Execution Order
+
+Workflow execution is not just about running tasks—it's about running them **in the correct order**, **with the correct prerequisites**, and **at the correct moment**. In FlowSynx, this process is governed by a powerful dependency model rooted in Directed Acyclic Graphs (DAGs). Dependencies define the logical and temporal relationships between tasks, ensuring that each step executes exactly when it should and that the workflow behaves consistently, even as it grows in complexity.
+
+## The Role of Dependencies in Workflow Design
+
+Dependencies specify which tasks must complete before another task can begin. In DAG terminology, these are represented as **directed edges** between nodes:
+
+- **Parent / Upstream Task** — A prerequisite  
+- **Child / Downstream Task** — A task that depends on one or more parents  
+
+A task *cannot* start until all upstream dependencies have completed successfully.
+
+### Basic Dependency Example
+
+<img src="/img/Basic-Dependency-Example.jpg" />
+
+## Validating Dependencies & Detecting Structural Problems
+
+To guarantee correctness before execution begins, FlowSynx automatically runs a series of structural validation checks. These checks ensure that the workflow is valid, executable, and free of ambiguous or inconsistent definitions.
+
+FlowSynx uses a combination of simple hash-based scans and a classic cycle-detection algorithm.
+
+
+### 1. Duplicate Task Detection (O(n))
+
+FlowSynx uses a **single-pass HashSet membership test** to ensure task names are unique:
+
+```
+for each task:
+    if task.Name in hashset: DUPLICATE
+    else add to hashset
+```
+
+#### Diagram
+<img src="/img/Duplicate-Task-Detection.jpg" />
+
+
+### 2. Missing Dependencies / Missing Branch Targets (O(V + E))
+
+FlowSynx builds a HashSet of all defined task names and checks whether dependencies reference anything that doesn't exist.
+
+<img src="/img/Missing-Dependencies.jpg" />
+
+### 3. Cyclic Dependency Detection (Kahn’s Algorithm) (O(V + E))
+
+FlowSynx uses **Kahn’s Algorithm**, a topological sort strategy, to detect cycles. Kahn’s Algorithm is a classic method for detecting cycles in a directed graph (like a workflow DAG).
+If the workflow has a cycle, you cannot topologically sort it, and that’s exactly how the algorithm detects the problem.
+
+#### Algorithm Steps
+- Each task is a node (V).
+- Each dependency is a directed edge (E): **A → B** means A must run before B.
+- We compute in-degree for each node:
+- How many tasks depend on this node?
+- Repeatedly remove nodes with in-degree = 0 (tasks with no unmet prerequisites).
+- Removing a node also removes its outgoing edges, lowering in-degrees of its neighbors.
+- If there is a cycle, some nodes will never reach in-degree 0.
+
+#### Diagram — No Cycle
+
+<img src="/img/DAG-NoCycle-Exists.jpg" />
+```
+in-degree:
+A:0, B:1, C:1
+
+Queue: [A]
+Pop A → decrement B → B:0 → enqueue B
+Pop B → decrement C → C:0 → enqueue C
+Pop C → done
+
+Processed = 3, Total = 3 → no cycle
+```
+
+#### Diagram — Cycle Exists
+<img src="/img/DAG-Cycle-Exists.jpg" />
+
+```
+in-degree:
+A:1, B:1, C:1
+
+Queue: (empty)
+
+Processed = 0 < 3 → cycle detected
+```
+
+## Dynamic Execution Planning in FlowSynx
+
+FlowSynx analyzes task dependencies and computes the execution plan dynamically.
+
+### Execution Flow Diagram
+<img src="/img/Execution-Flow-Diagram.jpg" />
+
+## Concurrency and Parallel Execution
+
+DAGs allow tasks with no dependency relationship to run concurrently.
+
+### Parallelism Example
+<img src="/img/Parallelism-Example.jpg" />
+
+A and B run in parallel; C waits for both.
+
+## Dependency-Driven Reliability
+
+### Error Isolation Diagram
+<img src="/img/Error-Isolation-Diagram.jpg" />
+
+```
+If [B] fails:
+   [C] blocked
+   [D] blocked
+   [E] blocked
+```
+
+FlowSynx can isolate the branch containing failures without affecting unrelated parts of the workflow.
+
+## Conditional Branching and Advanced Flows
+<img src="/img/Conditional-Branching-Flow.jpg" />
+
+## Scaling to Large Pipelines
+
+### Large Pipeline DAG
+<img src="/img/Large-Pipeline-DAG.jpg" />
+
+FlowSynx’s dependency model enables:
+
+- Automated ordering  
+- Fast topological sorting  
+- Predictable state transitions  
+- High concurrency  
+- Fine-grained error localization  
+- Improved debuggability through clear DAG visualization  
+
+---
+
+Proper dependency management is not just a feature of FlowSynx—it is one of the core principles enabling powerful, 
+reliable, and scalable workflow automation. By combining **hash-based validations**, **graph integrity checks**, and 
+**Kahn’s Algorithm**, FlowSynx ensures that every workflow is structurally sound *before a single task executes*. And 
+through DAG-driven scheduling, FlowSynx guarantees that each workflow runs exactly as intended, regardless of complexity or scale.

versioned_docs/version-1.2.x/concepts/directed-acyclic-graphs.mdx

@@ -0,0 +1,92 @@
+---
+sidebar_position: 2
+description: An introduction to Directed Acyclic Graphs (DAGs) and how they power deterministic, reliable, and parallelizable workflow orchestration in FlowSynx.
+---
+
+# Directed Acyclic Graphs (DAG)
+
+Directed Acyclic Graphs (DAGs) form the mathematical and architectural backbone of modern workflow orchestration systems. 
+In FlowSynx, DAGs provide the structure through which complex processes are broken down into manageable, deterministic 
+sequences of tasks. By enforcing directionality and prohibiting cycles, a DAG makes it possible to define workflows that 
+are predictable, parallelizable, and inherently safe from infinite loops.
+
+## What Is a DAG?
+
+A Directed Acyclic Graph is composed of **nodes** (representing tasks or operations) connected by **directed edges** 
+(representing dependencies or ordering constraints). Each edge points from one task to another, indicating that the 
+destination task cannot begin until the source task has completed. The term *acyclic* means that no circular paths 
+exist—following the arrows will never bring you back to a previously visited node.
+
+This property is essential in workflow systems because it ensures:
+
+- **Deterministic Execution**: The system can always compute a valid order of execution.
+- **No Circular Dependencies**: Workflows cannot deadlock or recurse indefinitely.
+- **Safe Parallelism**: Independent tasks can run simultaneously without risk of violating dependencies.
+- **Clear Visualization**: Engineers can easily understand and communicate workflow logic.
+
+## Why DAGs Matter in Workflow Orchestration
+
+Modern orchestration engines such as FlowSynx rely on DAGs to ensure reliability, scalability, and fault isolation 
+within complex processes. By having explicit dependencies, the workflow engine can decide *when* to execute a task, 
+*whether* it can be retried, and *how* failures should propagate.
+
+### Key Advantages
+
+### 1. Deterministic Ordering
+FlowSynx uses DAG analysis to compute the task execution order at runtime. Because no cycles exist, the engine can 
+always derive a topological sort—ensuring a clear, predictable sequence.
+
+### 2. Parallelization of Independent Tasks
+If multiple nodes have no dependencies on each other, FlowSynx can execute them concurrently. This dramatically improves 
+workflow throughput, especially in data-intensive or distributed environments.
+
+### 3. Fine-Grained Error Handling
+Each node runs independently, so failures can be isolated to specific branches. FlowSynx supports:
+
+- Dependency-aware retries  
+- Graceful degradation  
+- Fail-fast or fail-soft strategies  
+- Human-in-the-loop interventions (optional)
+
+### 4. Complex Logic Modeling
+DAGs are flexible enough to represent:
+
+- Conditional paths  
+- Branching and merging  
+- Loops expressed as *repeated tasks* rather than true cycles  
+- Multi-stage transformations  
+- Integration pipelines and event-driven operations  
+
+This makes DAGs suitable not only for data pipelines, but also CI/CD automation, ETL operations, distributed job coordination, 
+and business logic orchestration.
+
+## Real-World DAG Structure Example
+
+Below is an example visualization demonstrating how tasks can flow through multiple stages before converging. Notice that all 
+edges point forward, and no cycles occur. This ensures the workflow progresses cleanly from the starting node (“Task 1”) toward 
+the final output (“Task 8”).
+
+<img src="/img/DAG-example.jpg" />
+
+In this diagram:
+
+- **Task 1** initiates the workflow.  
+- Subsequent tasks branch out into parallel sub-processes.  
+- Independent tasks run concurrently, improving performance.  
+- All paths eventually merge at **Task 8**, forming a unified result.
+
+This pattern is common in real orchestration scenarios, such as data preparation pipelines or multi-step file processing workflows.
+
+## DAGs in FlowSynx
+
+FlowSynx takes advantage of DAGs not only for execution sequencing, but also for:
+
+- Workflow validation and structural integrity checks  
+- Automatic dependency resolution  
+- Optimized scheduling  
+- Cross-node context propagation  
+- Plugin-based task execution  
+- Visualization through the FlowSynx UI  
+
+By representing workflows as DAGs, FlowSynx ensures that every automation—whether simple or highly complex—remains maintainable, scalable, 
+and predictable.

versioned_docs/version-1.2.x/concepts/human-in-the-loop-tasks.mdx

@@ -0,0 +1,82 @@
+---
+sidebar_position: 8
+description: FlowSynx is fully container-ready, making it easy to deploy in isolated, reproducible environments using Docker. This option is highly recommended for users looking to minimize conflicts, simplify upgrades, and ensure consistent behavior across development, staging, and production environments.
+---
+
+# Human-in-the-Loop Tasks
+
+Automated workflows are powerful, but there are scenarios where **human judgment, approval, or input** is essential. FlowSynx supports this through **human-in-the-loop (HITL) tasks**, which pause workflow execution and require manual intervention before the workflow can continue. This capability combines automation with human oversight, enabling reliable, compliant, and flexible business processes.
+
+Human-in-the-loop tasks are particularly valuable for:
+
+- **Compliance and regulatory workflows**: Ensuring that sensitive operations meet legal or organizational requirements.  
+- **Quality control**: Verifying outputs before committing changes or publishing results.  
+- **Exception handling**: Allowing human operators to resolve errors or unexpected conditions.  
+- **Complex decision-making**: Where automation alone cannot determine the correct next step.  
+
+
+## How Human-in-the-Loop Works in FlowSynx
+
+In FlowSynx, human-in-the-loop tasks are **explicitly modeled as nodes within a DAG**. When the workflow reaches a HITL node:
+
+1. **Execution pauses** at the task.  
+2. The system **notifies the assigned user(s)** via the configured channels (email, web UI, or integrations with collaboration tools).  
+3. The user completes the required action—such as approving a request, entering data, or making a decision.  
+4. Once the task is completed, **workflow execution resumes**, following the downstream dependencies defined in the DAG.  
+
+This ensures that workflows maintain **deterministic execution order** even when human interaction is required.
+
+
+## Benefits of Human-in-the-Loop Tasks
+
+### 1. Compliance and Auditability
+HITL tasks leave a clear **audit trail**, recording who performed the action, when, and what decision was made. This is critical for industries such as finance, healthcare, or legal operations.
+
+### 2. Flexible Workflow Design
+Designers can incorporate human judgment only where necessary, while keeping other parts of the workflow fully automated.
+
+### 3. Error Mitigation
+By inserting human checkpoints, organizations reduce the risk of incorrect automated decisions or accidental data corruption.
+
+### 4. Seamless Integration with Automation
+HITL tasks coexist with automated retries, error handling, and data validation mechanisms, ensuring workflows remain resilient and robust even with manual interventions.
+
+### 5. Multi-User Collaboration
+Tasks can be assigned to individual users or groups, supporting parallel reviews, approvals, or joint decision-making.
+
+
+## Example Use Cases
+
+- **Invoice processing:** Automatically extract invoice data, but require human approval for amounts above a certain threshold.  
+- **Content publishing:** Automated content pipelines with human review before publishing articles or marketing material.  
+- **Medical imaging workflows:** Automatically process scans but require a radiologist to verify critical findings.  
+- **Financial transaction workflows:** Automated fraud detection triggers a human review for flagged transactions.  
+- **Customer support automation:** Automatically route tickets but require a human agent to confirm sensitive responses.  
+
+
+## Implementation Considerations
+
+When designing HITL tasks in FlowSynx:
+
+- Clearly **define the task owner or group** responsible for action.  
+- Configure **notifications and reminders** to prevent workflow stalling.  
+- Ensure **data visibility and security** so the assigned user has access to relevant information.  
+- Set **timeouts or escalation paths** for critical workflows to maintain continuity.  
+- Integrate **role-based permissions** to ensure only authorized users can complete specific tasks.  
+
+
+## Combining HITL with DAGs
+
+Human-in-the-loop tasks seamlessly integrate with FlowSynx’s **DAG-based workflow engine**, maintaining:
+
+- Clear **execution order** with upstream and downstream dependencies.  
+- **Retry and error-handling logic** around manual tasks.  
+- Consistency in **data propagation** and **state management** across automated and manual steps.  
+
+This makes it possible to build **hybrid workflows** that combine the efficiency of automation with the intelligence of human decision-making.
+
+---
+
+Human-in-the-loop tasks are a cornerstone for building **robust, compliant, and intelligent workflows** in FlowSynx. 
+By explicitly modeling points of human intervention within a DAG, organizations can balance automation speed with oversight, 
+ensuring workflows remain both efficient and reliable.