# akram48616/flowforge architecture

> Architecture diagram of the GitHub repository akram48616/flowforge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akram48616/flowforge
- Repository: https://github.com/akram48616/flowforge

## Overview

FlowForge is a distributed workflow orchestration platform. A client submits a workflow through the gateway; the workflow service validates and stores its dependency graph. An execution request leads the execution service to fetch that definition, track task state, and dispatch ready tasks through Kafka. Workers execute task types and publish results; execution coordination handles retries, stale-dispatch recovery, and terminal status, which notifications consume. The README documents these cross-service flows; internal links not established by the supplied source excerpts are omitted.

Main entry points: [`execution-service/src/main/java/com/example/execution/service/ExecutionService.java`](https://github.com/akram48616/flowforge/blob/main/execution-service/src/main/java/com/example/execution/service/ExecutionService.java) (Execution Service), [`workflow-service/src/main/java/com/example/workflow/service/WorkflowService.java`](https://github.com/akram48616/flowforge/blob/main/workflow-service/src/main/java/com/example/workflow/service/WorkflowService.java) (Workflow Service), [`service-registry/src/main/java/com/example/registry/ServiceRegistryApplication.java`](https://github.com/akram48616/flowforge/blob/main/service-registry/src/main/java/com/example/registry/ServiceRegistryApplication.java) (Service Registry), [`api-gateway/src/main/java/com/example/gateway/ApiGatewayApplication.java`](https://github.com/akram48616/flowforge/blob/main/api-gateway/src/main/java/com/example/gateway/ApiGatewayApplication.java) (API Gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["API ingress"]
  node_gateway["API Gateway"]
end

subgraph group_definitions["Workflow definitions"]
  node_workflow["Workflow Service"]
  node_cycle["Cycle Detection<br/>[CycleDetector.java]"]
  node_workflowdb[("Workflow MySQL")]
end

subgraph group_runtime["Execution runtime"]
  node_execution["Execution Service"]
  node_dag["DAG Executor<br/>[DagExecutor.java]"]
  node_scheduler["Recovery Scheduler"]
  node_lock["Distributed Lock"]
  node_executiondb[("Execution MySQL")]
  node_resultconsumer["Result Consumer"]
end

subgraph group_tasks["Task processing"]
  node_worker["Worker Service<br/>[WorkerService.java]"]
  node_taskconsumer["Task Consumer<br/>[TaskConsumer.java]"]
  node_taskexecutors["Task Executors"]
  node_resultproducer["Result Producer"]
  node_notification["Notification Service"]
end

subgraph group_platform["Coordination services"]
  node_kafka["Kafka"]
  node_dlq["Dead-letter Topic"]
  node_status["Workflow Status Topic"]
  node_redis[("Redis")]
  node_registry["Service Registry"]
end

node_client(("Client"))

node_client -->|"submits requests"| node_gateway
node_gateway -->|"routes requests"| node_workflow
node_gateway -->|"routes requests"| node_execution
node_workflow -->|"validates DAG"| node_cycle
node_workflow -->|"persists definitions"| node_workflowdb
node_execution -->|"fetches DAG"| node_workflow
node_execution -->|"advances DAG"| node_dag
node_execution -->|"stores run state"| node_executiondb
node_execution -->|"dispatches tasks"| node_kafka
node_kafka -->|"delivers tasks"| node_taskconsumer
node_taskconsumer -->|"routes tasks"| node_worker
node_worker -->|"executes task types"| node_taskexecutors
node_worker -->|"publishes results"| node_resultproducer
node_resultproducer -->|"sends task results"| node_kafka
node_kafka -->|"delivers results"| node_resultconsumer
node_resultconsumer -->|"advances execution"| node_execution
node_scheduler -->|"requeues stale tasks"| node_kafka
node_execution -->|"publishes exhausted tasks"| node_dlq
node_execution -->|"publishes terminal status"| node_status
node_status -->|"delivers status"| node_notification
node_execution -->|"coordinates locks"| node_redis
node_gateway -.->|"registers with"| node_registry
node_workflow -.->|"registers with"| node_registry
node_execution -.->|"registers with"| node_registry
node_worker -.->|"registers with"| node_registry
node_notification -.->|"registers with"| node_registry

click node_gateway "https://github.com/akram48616/flowforge/blob/main/api-gateway/src/main/java/com/example/gateway/ApiGatewayApplication.java"
click node_workflow "https://github.com/akram48616/flowforge/blob/main/workflow-service/src/main/java/com/example/workflow/service/WorkflowService.java"
click node_cycle "https://github.com/akram48616/flowforge/blob/main/workflow-service/src/main/java/com/example/workflow/service/CycleDetector.java"
click node_execution "https://github.com/akram48616/flowforge/blob/main/execution-service/src/main/java/com/example/execution/service/ExecutionService.java"
click node_dag "https://github.com/akram48616/flowforge/blob/main/execution-service/src/main/java/com/example/execution/service/DagExecutor.java"
click node_scheduler "https://github.com/akram48616/flowforge/blob/main/execution-service/src/main/java/com/example/execution/service/SchedulerService.java"
click node_lock "https://github.com/akram48616/flowforge/blob/main/execution-service/src/main/java/com/example/execution/service/DistributedLockService.java"
click node_worker "https://github.com/akram48616/flowforge/blob/main/worker-service/src/main/java/com/example/worker/service/WorkerService.java"
click node_taskconsumer "https://github.com/akram48616/flowforge/blob/main/worker-service/src/main/java/com/example/worker/kafka/TaskConsumer.java"
click node_taskexecutors "https://github.com/akram48616/flowforge/tree/main/worker-service/src/main/java/com/example/worker/executor"
click node_resultproducer "https://github.com/akram48616/flowforge/blob/main/worker-service/src/main/java/com/example/worker/kafka/TaskResultProducer.java"
click node_resultconsumer "https://github.com/akram48616/flowforge/blob/main/execution-service/src/main/java/com/example/execution/kafka/TaskResultConsumer.java"
click node_notification "https://github.com/akram48616/flowforge/blob/main/notification-service/src/main/java/com/example/notification/kafka/WorkflowStatusConsumer.java"
click node_registry "https://github.com/akram48616/flowforge/blob/main/service-registry/src/main/java/com/example/registry/ServiceRegistryApplication.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gateway,node_client toneBlue
class node_workflow,node_cycle,node_workflowdb toneAmber
class node_execution,node_dag,node_scheduler,node_lock,node_executiondb,node_resultconsumer toneMint
class node_worker,node_taskconsumer,node_taskexecutors,node_resultproducer,node_notification toneRose
class node_kafka,node_dlq,node_status,node_redis,node_registry toneIndigo
```

## Components

### API ingress

- [API Gateway](https://github.com/akram48616/flowforge/blob/main/api-gateway/src/main/java/com/example/gateway/ApiGatewayApplication.java): `api-gateway/src/main/java/com/example/gateway/ApiGatewayApplication.java`

### Workflow definitions

- [Workflow Service](https://github.com/akram48616/flowforge/blob/main/workflow-service/src/main/java/com/example/workflow/service/WorkflowService.java): `workflow-service/src/main/java/com/example/workflow/service/WorkflowService.java`
- [Cycle Detection](https://github.com/akram48616/flowforge/blob/main/workflow-service/src/main/java/com/example/workflow/service/CycleDetector.java): `workflow-service/src/main/java/com/example/workflow/service/CycleDetector.java`
- **Workflow MySQL**

### Execution runtime

- [Execution Service](https://github.com/akram48616/flowforge/blob/main/execution-service/src/main/java/com/example/execution/service/ExecutionService.java): `execution-service/src/main/java/com/example/execution/service/ExecutionService.java`
- [DAG Executor](https://github.com/akram48616/flowforge/blob/main/execution-service/src/main/java/com/example/execution/service/DagExecutor.java): `execution-service/src/main/java/com/example/execution/service/DagExecutor.java`
- [Recovery Scheduler](https://github.com/akram48616/flowforge/blob/main/execution-service/src/main/java/com/example/execution/service/SchedulerService.java): `execution-service/src/main/java/com/example/execution/service/SchedulerService.java`
- [Distributed Lock](https://github.com/akram48616/flowforge/blob/main/execution-service/src/main/java/com/example/execution/service/DistributedLockService.java): `execution-service/src/main/java/com/example/execution/service/DistributedLockService.java`
- **Execution MySQL**
- [Result Consumer](https://github.com/akram48616/flowforge/blob/main/execution-service/src/main/java/com/example/execution/kafka/TaskResultConsumer.java): `execution-service/src/main/java/com/example/execution/kafka/TaskResultConsumer.java`

### Task processing

- [Worker Service](https://github.com/akram48616/flowforge/blob/main/worker-service/src/main/java/com/example/worker/service/WorkerService.java): `worker-service/src/main/java/com/example/worker/service/WorkerService.java`
- [Task Consumer](https://github.com/akram48616/flowforge/blob/main/worker-service/src/main/java/com/example/worker/kafka/TaskConsumer.java): `worker-service/src/main/java/com/example/worker/kafka/TaskConsumer.java`
- [Task Executors](https://github.com/akram48616/flowforge/tree/main/worker-service/src/main/java/com/example/worker/executor): `worker-service/src/main/java/com/example/worker/executor`
- [Result Producer](https://github.com/akram48616/flowforge/blob/main/worker-service/src/main/java/com/example/worker/kafka/TaskResultProducer.java): `worker-service/src/main/java/com/example/worker/kafka/TaskResultProducer.java`
- [Notification Service](https://github.com/akram48616/flowforge/blob/main/notification-service/src/main/java/com/example/notification/kafka/WorkflowStatusConsumer.java): `notification-service/src/main/java/com/example/notification/kafka/WorkflowStatusConsumer.java`

### Coordination services

- **Kafka**
- **Dead-letter Topic**
- **Workflow Status Topic**
- **Redis**
- [Service Registry](https://github.com/akram48616/flowforge/blob/main/service-registry/src/main/java/com/example/registry/ServiceRegistryApplication.java): `service-registry/src/main/java/com/example/registry/ServiceRegistryApplication.java`

### Other components

- **Client**

## Connections

- Client → API Gateway: submits requests (evidence: `README.md`)
- API Gateway → Workflow Service: routes requests (evidence: `README.md`)
- API Gateway → Execution Service: routes requests (evidence: `README.md`)
- Workflow Service → Cycle Detection: validates DAG (evidence: `README.md`)
- Workflow Service → Workflow MySQL: persists definitions (evidence: `README.md`)
- Execution Service → Workflow Service: fetches DAG (evidence: `README.md`)
- Execution Service → DAG Executor: advances DAG (evidence: `README.md`)
- Execution Service → Execution MySQL: stores run state (evidence: `README.md`)
- Execution Service → Kafka: dispatches tasks (evidence: `README.md`)
- Kafka → Task Consumer: delivers tasks (evidence: `README.md`)
- Task Consumer → Worker Service: routes tasks (evidence: `README.md`)
- Worker Service → Task Executors: executes task types (evidence: `README.md`)
- Worker Service → Result Producer: publishes results (evidence: `README.md`)
- Result Producer → Kafka: sends task results (evidence: `README.md`)
- Kafka → Result Consumer: delivers results (evidence: `README.md`)
- Result Consumer → Execution Service: advances execution (evidence: `README.md`)
- Recovery Scheduler → Kafka: requeues stale tasks (evidence: `README.md`)
- Execution Service → Dead-letter Topic: publishes exhausted tasks (evidence: `README.md`)
- Execution Service → Workflow Status Topic: publishes terminal status (evidence: `README.md`)
- Workflow Status Topic → Notification Service: delivers status (evidence: `README.md`)
- Execution Service → Redis: coordinates locks (evidence: `README.md`)
- API Gateway → Service Registry: registers with (evidence: `README.md`)
- Workflow Service → Service Registry: registers with (evidence: `README.md`)
- Execution Service → Service Registry: registers with (evidence: `README.md`)
- Worker Service → Service Registry: registers with (evidence: `README.md`)
- Notification Service → Service Registry: registers with (evidence: `README.md`)