ut.Let's talk
All projects
Backend & workflow systems / Tested implementation

ForgeQueue.

Workflows that survive the unhappy path.

Explore the repository
REPORT WORKFLOW / ILLUSTRATION

Two inputs. One useful result.

  1. PARALLEL INPUTSRead customers + read orders
  2. WAIT FOR BOTHValidate & aggregate
  3. ONLY ON SUCCESSWrite Markdown report

The repository records five fixture orders totaling $485.00. Invalid input blocks the report. This diagram is not a live run.

WHAT IT DOES

A Go job queue and workflow engine with durable dispatch, recoverable workers, and an operations console that makes execution inspectable.

MY CONTRIBUTION

Solo project: backend workflow engine, worker SDK, operations console, tests, and deployment tooling. Solo ownership was confirmed by Usman.

THE INTERESTING DECISION

A job and its outbox record commit in one PostgreSQL transaction. The relay publishes with RabbitMQ confirms and can retry; duplicate delivery is expected, not hidden behind an exactly-once claim.

START WITH THE EVIDENCEPassing CI

GitHub Actions run 38591930872 passed for commit 694f400. Its configured gates include race-enabled Go tests with PostgreSQL/RabbitMQ, frontend checks, configuration validation, and image builds. This is a dated run, not a permanent guarantee.

Inspect the source ↗
BUILT WITH
GoPostgreSQLRabbitMQTypeScriptReactOpenTelemetryDocker
PROJECT TYPE

Tested implementation

START HEREREADME & setup
01 / THE IDEA

Workflows that survive the unhappy path.

The problem

Background work can fail between accepting a request, publishing it to a broker, and saving its result. Multi-step workflows also need to know which inputs are ready, which attempts failed, and whether downstream work should run at all.

The approach

ForgeQueue commits jobs and delivery intent together in PostgreSQL, then uses RabbitMQ to signal workers. Renewable leases and fencing tokens protect saved completion state. DAG dependencies release ready steps, typed handlers validate input, and the embedded React console exposes jobs, attempts, events, and recovery controls.

02 / THE SYSTEM AT A GLANCE

Follow the flow.

  1. 01Submit DAG
  2. 02Commit state + outbox
  3. 03Deliver via RabbitMQ
  4. 04Run typed handlers
  5. 05Persist result + release steps

A simplified architecture overview. The repository documents the implementation details.

03 / THE ENGINEERING DECISIONS

Why it's built this way.

01

Commit before dispatch

A job and its outbox record commit in one PostgreSQL transaction. The relay publishes with RabbitMQ confirms and can retry; duplicate delivery is expected, not hidden behind an exactly-once claim.

02

Fence the saved result

Claiming a job advances its lease token. Completion checks that token and active state, so an old worker cannot overwrite a reclaimed attempt. External handler side effects still need application-level idempotency.

03

Make workflows do real work

The report example loads customers and orders independently, resolves their outputs into a validated join, and writes deterministic Markdown. Invalid customer references are permanent errors and block the downstream report.

04

Separate the worker contract

The public Go registry supports typed JSON inputs/results, progress, logs, context cancellation, panic containment, and permanent errors. Custom workers do not need the unsafe command handler, which is disabled by default.

04 / WHAT TO LOOK AT

Evidence over adjectives.

Reviewed commit CIPassing CI

GitHub Actions run 38591930872 passed for commit 694f400. Its configured gates include race-enabled Go tests with PostgreSQL/RabbitMQ, frontend checks, configuration validation, and image builds. This is a dated run, not a permanent guarantee.

Real report example4-step DAG

The repository records a local run joining three customers and five orders into a $485.00 Markdown report. These are bundled demo fixtures, not throughput measurements or real customer data.

Failure-oriented testsRecovery + fencing

Committed integration tests cover duplicate claims, exhausted retries, expired leases, stale-result rejection, workflow dependency release, and transactional outbox delivery.

Worker extensionTyped Go SDK

Strict payload decoding, permanent validation failures, panic containment, and retry-safe report writing have dedicated tests and runnable custom-worker examples.

Capabilities and result snapshots follow the project's current README, reviewed October 14, 2026. Read the source

Architecture and guaranteesReport workflow and recorded resultRecovery integration testsReport workflow testsRemaining production work
05 / THE HONEST PART

What I'd improve next.

Current boundaries

  • At-least-once execution does not make external side effects exactly once; handlers need their own idempotency strategy.
  • The checked-in load baseline is pending. No production throughput, latency, scale, uptime, or hosted deployment is claimed.
  • Live MinIO validation, streaming/multipart uploads, restore drills, and broader production hardening remain incomplete. The report demo writes local files, not S3 artifacts.
  • Schedule authorization and concurrent quota/cap enforcement need deeper hardening before multi-tenant production use. CI's coverage gate is only 5%; a passing run is not exhaustive correctness evidence.
  • Cron/time-zone scheduling and signed webhooks are planned. The visual builder currently supports built-in handlers; submit the report examples through the API/script.

The next iteration

Close the authorization and concurrency edge cases, strengthen coverage around workflow failure propagation, run fresh-stack storage/chaos/load and restore checks, then capture a concise real console recording. Keep measured results tied to a commit and environment.

Open my Cloud & DevOps CV
KEEP EXPLORING

ClaimGuard

Check the claim. Preserve the rest.