# mahabubulhasibshawon/task_saga_workflow_orchestrator architecture

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

- Interactive diagram: https://gitdiagram.com/mahabubulhasibshawon/task_saga_workflow_orchestrator
- Repository: https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator

## Overview

1. **Overall shape**
   - This repository is a Go-based **Saga workflow orchestrator** for order processing.
   - It follows a **clean architecture split**: `cmd` entrypoints → `internal/usecases` business logic → `internal/repositories` persistence → `internal/adapters` integration concerns.
   - The system coordinates long-running workflows with **forward steps**, **compensation steps**, and **recovery**.

2. **Runtime entrypoints**
   - `cmd/orchestrator` is the main worker process: it starts the workflow execution runtime, queue consumers, metrics, and tracing.
   - `cmd/simulate` generates synthetic orders to drive the workflow.
   - `cmd/recover` scans for stalled workflows and resumes them.
   - These are separate binaries rather than one monolith, which is important for the deployment diagram.

3. **Workflow control plane**
   - `internal/usecases/workflow.go` and `internal/usecases/compensation.go` are the orchestration core.
   - They decide the current step, advance the saga, and trigger rollback when a step fails.
   - The workflow model is step-based, with forward steps like `reserve_pickup_slot → assign_agent → notify_customer` and compensation steps like `unassign_agent → release_slot → cancel_notification`.

4. **Domain model boundaries**
   - `internal/domain` contains the core entities and interfaces:
     - `order.go`
     - `workflow_state.go`
     - repository interfaces for orders, agents, workflow state, and step execution
   - This layer defines the business concepts without depending on Postgres, Redis, or queue libraries.
   - The domain interfaces are the boundary that the repositories implement.

5. **Persistence layer**
   - `internal/repositories` contains concrete database access for orders, workflows, agents, and step executions.
   - The schema is split across four tables:
     - `orders` for order status
     - `workflows` for current step and overall state
     - `step_executions` for idempotency and deduplication
     - `agents` for multiple agents assigned per order
   - This persistence layer is the source of truth for workflow state and retry safety.

6. **Queue and task execution**
   - `internal/adapters/queue` and `internal/adapters/handlers` connect the workflow logic to background task execution.
   - The README indicates the queue runtime is based on **Asynq**, with Redis acting as the task broker.
   - The queue boundary is where workflow steps are dispatched asynchronously and retried independently of the CLI that initiated them.

7. **External infrastructure**
   - `docker-compose.yml` provisions the required infrastructure: **Postgres** and **Redis**.
   - `pkg/conn/postgress.go` centralizes the Postgres connection setup.
   - The architecture therefore depends on two backing services:
     - Postgres for durable workflow state
     - Redis for task queue transport

8. **Observability**
   - `internal/adapters/metrics` exposes Prometheus metrics for step success, step failure, and compensation counts.
   - `internal/adapters/tracing` wires in **OpenTelemetry** for distributed tracing across workflow steps.
   - `cmd/orchestrator` is the process where these observability adapters matter most, because it is the active worker handling workflow transitions.

9. **Failure handling and recovery**
   - The saga is designed to tolerate partial failure: if a forward step fails, compensation is executed for prior completed steps.
   - Idempotency is handled through `step_executions`, so re-delivered tasks or retried steps do not duplicate side effects.
   - `cmd/recover` provides an explicit recovery path for workflows left in an in-between state after crashes or outages.

10. **Mockable service boundary**
   - `pkg/mocks` contains in-memory or DB-backed service stand-ins used by the workflow logic.
   - This suggests the step execution side effects are abstracted so the orchestrator can be tested or simulated without real downstream microservices.
   - For architecture diagrams, this is the “external business services” boundary even though the repo currently ships with mocks.

11. **Schema evolution**
   - `migrations/` contains versioned SQL migrations for all durable entities.
   - This means the workflow state machine is strongly coupled to the relational schema, and deployment requires database migration before running the orchestrator.
   - The DB schema is part of the system contract, not just an implementation detail.

12. **End-to-end data flow**
   - `simulate` creates orders.
   - Order state is persisted in Postgres.
   - The orchestrator schedules and processes saga steps via the queue.
   - Each step updates workflow state and step execution history.
   - On success, the workflow advances; on failure, compensation is triggered.
   - Metrics and traces are emitted throughout the process, and `recover` can resume incomplete workflows later.

13. **Key architectural boundaries to draw**
   - Boundary 1: CLI entrypoints vs. long-running worker/runtime.
   - Boundary 2: orchestration/use case layer vs. persistence implementation.
   - Boundary 3: core workflow domain vs. queue/metrics/tracing adapters.
   - Boundary 4: durable Postgres state vs. ephemeral Redis queue state.
   - Boundary 5: orchestrator core vs. mocked downstream business services.

Main entry points: [`internal/usecases/workflow.go`](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/usecases/workflow.go) (Workflow usecase), [`cmd/orchestrator/main.go`](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/cmd/orchestrator/main.go) (Orchestrator), [`docker-compose.yml`](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/docker-compose.yml) (Postgres), [`internal/adapters/handlers/handlers.go`](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/adapters/handlers/handlers.go) (Handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_cmd["Entry points"]
  node_node_orchestrator["Orchestrator<br/>worker binary<br/>[main.go]"]
  node_node_simulate["Simulate<br/>generator binary<br/>[main.go]"]
  node_node_recover["Recover<br/>[main.go]"]
end

subgraph group_grp_core["Core workflow"]
  node_node_workflow["Workflow usecase<br/>orchestration logic<br/>[workflow.go]"]
  node_node_compensation["Compensation usecase<br/>rollback logic<br/>[compensation.go]"]
  node_node_domain_order["Order model<br/>domain entity<br/>[order.go]"]
  node_node_domain_workflow["Workflow state<br/>domain entity<br/>[workflow_state.go]"]
  node_node_domain_order_repo["Order repo iface<br/>domain port"]
  node_node_domain_agent_repo["Agent repo iface<br/>domain port"]
  node_node_domain_workflow_repo["Workflow repo iface<br/>domain port"]
  node_node_domain_step_repo["Step exec iface<br/>domain port"]
end

subgraph group_grp_data["Persistence"]
  node_node_repo_orders[("Order repo<br/>postgres repository<br/>[order_repo.go]")]
  node_node_repo_agents[("Agent repo<br/>postgres repository<br/>[agent_repo.go]")]
  node_node_repo_workflows[("Workflow repo<br/>postgres repository<br/>[workflow_repo.go]")]
  node_node_repo_steps[("Step exec repo<br/>postgres repository")]
  node_node_migrations["Migrations<br/>sql schema"]
  node_node_conn["Postgres conn<br/>db connector<br/>[postgress.go]"]
end

subgraph group_grp_adapters["Adapters"]
  node_node_queue["Queue adapter<br/>asynq broker<br/>[queue.go]"]
  node_node_handlers["Handlers<br/>[handlers.go]"]
  node_node_metrics(("Metrics<br/>prometheus<br/>[metrics.go]"))
  node_node_tracing(("Tracing<br/>opentelemetry<br/>[tracing.go]"))
  node_node_mocks["Service mocks<br/>external boundary<br/>[services.go]"]
end

subgraph group_grp_infra["Infrastructure"]
  node_node_redis[("Redis<br/>task broker<br/>[docker-compose.yml]")]
  node_node_postgres[("Postgres<br/>durable store<br/>[docker-compose.yml]")]
end

node_node_simulate -->|"creates orders"| node_node_workflow
node_node_orchestrator -->|"runs tasks"| node_node_queue
node_node_orchestrator -->|"executes steps"| node_node_handlers
node_node_orchestrator -->|"emits"| node_node_metrics
node_node_orchestrator -->|"traces"| node_node_tracing
node_node_recover -->|"resumes"| node_node_workflow
node_node_handlers -->|"advances"| node_node_workflow
node_node_workflow -->|"on failure"| node_node_compensation
node_node_workflow -->|"uses"| node_node_domain_order
node_node_workflow -->|"uses"| node_node_domain_workflow
node_node_workflow -->|"depends on"| node_node_domain_order_repo
node_node_workflow -->|"depends on"| node_node_domain_agent_repo
node_node_workflow -->|"depends on"| node_node_domain_workflow_repo
node_node_workflow -->|"depends on"| node_node_domain_step_repo
node_node_compensation -->|"records"| node_node_domain_step_repo
node_node_repo_orders -->|"stores in"| node_node_postgres
node_node_repo_agents -->|"stores in"| node_node_postgres
node_node_repo_workflows -->|"stores in"| node_node_postgres
node_node_repo_steps -->|"stores in"| node_node_postgres
node_node_migrations -->|"defines schema"| node_node_postgres
node_node_conn -->|"connects"| node_node_postgres
node_node_queue -->|"brokers on"| node_node_redis
node_node_handlers -->|"consumes from"| node_node_queue
node_node_handlers -->|"calls"| node_node_mocks
node_node_orchestrator -->|"initializes"| node_node_conn

click node_node_orchestrator "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/cmd/orchestrator/main.go"
click node_node_simulate "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/cmd/simulate/main.go"
click node_node_recover "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/cmd/recover/main.go"
click node_node_workflow "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/usecases/workflow.go"
click node_node_compensation "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/usecases/compensation.go"
click node_node_domain_order "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/domain/order.go"
click node_node_domain_workflow "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/domain/workflow_state.go"
click node_node_domain_order_repo "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/domain/order_repo_interface.go"
click node_node_domain_agent_repo "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/domain/agent_repo_interface.go"
click node_node_domain_workflow_repo "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/domain/workflow_state_repo_interface.go"
click node_node_domain_step_repo "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/domain/step_execution_repo_interface.go"
click node_node_repo_orders "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/repositories/order_repo.go"
click node_node_repo_agents "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/repositories/agent_repo.go"
click node_node_repo_workflows "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/repositories/workflow_repo.go"
click node_node_repo_steps "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/repositories/step_execution_repo.go"
click node_node_migrations "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/migrations/003_create_workflows.up.sql"
click node_node_conn "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/pkg/conn/postgress.go"
click node_node_queue "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/adapters/queue/queue.go"
click node_node_handlers "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/adapters/handlers/handlers.go"
click node_node_metrics "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/adapters/metrics/metrics.go"
click node_node_tracing "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/adapters/tracing/tracing.go"
click node_node_mocks "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/pkg/mocks/services.go"
click node_node_redis "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/docker-compose.yml"
click node_node_postgres "https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/docker-compose.yml"

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_node_orchestrator,node_node_simulate,node_node_recover toneBlue
class node_node_workflow,node_node_compensation,node_node_domain_order,node_node_domain_workflow,node_node_domain_order_repo,node_node_domain_agent_repo,node_node_domain_workflow_repo,node_node_domain_step_repo toneAmber
class node_node_repo_orders,node_node_repo_agents,node_node_repo_workflows,node_node_repo_steps,node_node_migrations,node_node_conn toneMint
class node_node_queue,node_node_handlers,node_node_metrics,node_node_tracing,node_node_mocks toneRose
class node_node_redis,node_node_postgres toneIndigo
```

## Components

### Entry points

Separate binaries that start, drive, or recover workflow execution.

- [Orchestrator](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/cmd/orchestrator/main.go): worker binary · Main long-running process that executes saga steps and coordinates runtime concerns. · `cmd/orchestrator/main.go`
- [Simulate](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/cmd/simulate/main.go): generator binary · Creates synthetic orders to drive the workflow end to end. · `cmd/simulate/main.go`
- [Recover](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/cmd/recover/main.go): recovery binary · Scans for stalled workflows and resumes incomplete executions. · `cmd/recover/main.go`

### Core workflow

Domain and use cases that implement saga orchestration logic.

- [Workflow usecase](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/usecases/workflow.go): orchestration logic · Advances saga steps, decides next actions, and coordinates forward execution. · `internal/usecases/workflow.go`
- [Compensation usecase](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/usecases/compensation.go): rollback logic · Triggers and sequences compensating actions when a forward step fails. · `internal/usecases/compensation.go`
- [Order model](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/domain/order.go): domain entity · Core order business object and state. · `internal/domain/order.go`
- [Workflow state](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/domain/workflow_state.go): domain entity · Saga state machine data and current step tracking. · `internal/domain/workflow_state.go`
- [Order repo iface](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/domain/order_repo_interface.go): domain port · Persistence boundary for order data access. · `internal/domain/order_repo_interface.go`
- [Agent repo iface](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/domain/agent_repo_interface.go): domain port · Persistence boundary for agent assignment data. · `internal/domain/agent_repo_interface.go`
- [Workflow repo iface](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/domain/workflow_state_repo_interface.go): domain port · Persistence boundary for workflow state and step progression. · `internal/domain/workflow_state_repo_interface.go`
- [Step exec iface](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/domain/step_execution_repo_interface.go): domain port · Boundary for idempotency and step execution history. · `internal/domain/step_execution_repo_interface.go`

### Persistence

Postgres-backed repositories, schema migrations, and connection setup.

- [Order repo](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/repositories/order_repo.go): postgres repository · Concrete persistence for orders table. · `internal/repositories/order_repo.go`
- [Agent repo](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/repositories/agent_repo.go): postgres repository · Concrete persistence for agents table and assignment records. · `internal/repositories/agent_repo.go`
- [Workflow repo](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/repositories/workflow_repo.go): postgres repository · Stores current workflow state and overall saga progress. · `internal/repositories/workflow_repo.go`
- [Step exec repo](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/repositories/step_execution_repo.go): postgres repository · Stores step execution history for retry safety and deduplication. · `internal/repositories/step_execution_repo.go`
- [Migrations](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/migrations/003_create_workflows.up.sql): sql schema · Versioned schema for orders, agents, workflows, and step executions. · `migrations/003_create_workflows.up.sql`
- [Postgres conn](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/pkg/conn/postgress.go): db connector · Shared Postgres connection setup used by repositories and runtime. · `pkg/conn/postgress.go`

### Adapters

Queue, handlers, observability, and external service boundaries.

- [Queue adapter](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/adapters/queue/queue.go): asynq broker · Dispatches saga steps asynchronously through Redis-backed tasks. · `internal/adapters/queue/queue.go`
- [Handlers](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/adapters/handlers/handlers.go): task handlers · Executes queued workflow step tasks and invokes use cases. · `internal/adapters/handlers/handlers.go`
- [Metrics](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/adapters/metrics/metrics.go): prometheus · Emits step success, failure, and compensation counters. · `internal/adapters/metrics/metrics.go`
- [Tracing](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/internal/adapters/tracing/tracing.go): opentelemetry · Propagates distributed traces across workflow execution. · `internal/adapters/tracing/tracing.go`
- [Service mocks](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/pkg/mocks/services.go): external boundary · Stand-ins for downstream business services used by workflow execution. · `pkg/mocks/services.go`

### Infrastructure

Runtime and deployment dependencies used by the system.

- [Redis](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/docker-compose.yml): task broker · Ephemeral queue transport for asynchronous workflow steps. · `docker-compose.yml`
- [Postgres](https://github.com/mahabubulhasibshawon/task_saga_workflow_orchestrator/blob/main/docker-compose.yml): durable store · Primary durable database for workflow and order state. · `docker-compose.yml`

## Connections

- Simulate → Workflow usecase: creates orders · Synthetic orders enter the orchestration flow through the business logic.
- Orchestrator → Queue adapter: runs tasks · Main worker consumes and dispatches saga work through the queue.
- Orchestrator → Handlers: executes steps · Worker runtime invokes task handlers for workflow step execution.
- Orchestrator → Metrics: emits · Worker process publishes execution metrics.
- Orchestrator → Tracing: traces · Worker process participates in distributed tracing.
- Recover → Workflow usecase: resumes · Recovery process re-enters stalled workflows through orchestration logic.
- Handlers → Workflow usecase: advances · Queue tasks delegate step progression to the workflow use case.
- Workflow usecase → Compensation usecase: on failure · Failed forward steps trigger compensation sequencing.
- Workflow usecase → Order model: uses · Workflow logic operates on order state.
- Workflow usecase → Workflow state: uses · Workflow logic reads and updates saga state.
- Workflow usecase → Order repo iface: depends on · Use case depends on the order persistence boundary.
- Workflow usecase → Agent repo iface: depends on · Use case depends on agent assignment boundary.
- Workflow usecase → Workflow repo iface: depends on · Use case depends on workflow state boundary.
- Workflow usecase → Step exec iface: depends on · Use case depends on step execution history boundary.
- Compensation usecase → Step exec iface: records · Compensation uses step execution history for safe retries.
- Order repo → Postgres: stores in · Order repository persists to Postgres.
- Agent repo → Postgres: stores in · Agent repository persists to Postgres.
- Workflow repo → Postgres: stores in · Workflow repository persists to Postgres.
- Step exec repo → Postgres: stores in · Step execution repository persists to Postgres.
- Migrations → Postgres: defines schema · SQL migrations create and evolve the durable schema.
- Postgres conn → Postgres: connects · Shared connection setup targets Postgres.
- Queue adapter → Redis: brokers on · Asynq queue adapter uses Redis as task transport.
- Handlers → Queue adapter: consumes from · Handlers process queued step jobs.
- Handlers → Service mocks: calls · Workflow steps interact with mocked downstream business services.
- Orchestrator → Postgres conn: initializes · Worker starts database connectivity during boot.