Workflow Engine Assessment

Overview

This project implements a configurable approval workflow engine for a property management platform using Go, PostgreSQL, pgxpool, and Chi router.

The engine supports:

• Configurable workflow templates
• Sequential approval flows
• User or role-based approvers
• Runtime workflow instances
• Immutable audit logging
• Concurrency-safe approvals
• Polymorphic workflow entities
• Workflow approval/rejection callbacks

Example business scenarios:

• Booking cancellation approval
• Unit price update approval
• Commission approval workflows

---

Tech Stack

• Go 1.24
• PostgreSQL
• pgxpool
• Chi Router
• SQL migrations
• Bash automation scripts

---

Project Structure

cmd/api/
    main.go

internal/httpapi/
    handler.go
    mock.go

internal/workflow/
    approve.go
    reject.go
    trigger.go
    template.go
    instance.go
    service.go
    model.go
    error.go

migrations/
    001_default.sql
    002_seed.sql

script/
    test_api.sh
    test_concurrency.sh

README.md
Makefile

---

Setup Instructions

1. Clone Repository

git clone <repo>
cd <repo>

---

2. Create PostgreSQL Database

createdb workflow_engine

---

3. Configure Environment

Create .env

DATABASE_URL=postgres://postgres:postgres@localhost:5432/workflow_engine?sslmode=disable

---

4. Run Migrations

psql "$DATABASE_URL" -f migrations/001_default.sql
psql "$DATABASE_URL" -f migrations/002_seed.sql

---

5. Start API

go run ./cmd/api

Server:

http://localhost:8080

---

Automated API Testing

The repository includes automated API testing scripts.

Run:

./script/test_api.sh

This script will:

1. Reset the database
2. Re-run migrations
3. Seed test data
4. Start the API server
5. Execute workflow lifecycle API tests
6. Validate workflow progression

---

Concurrency Testing

Run:

./script/test_concurrency.sh

This validates that only one approver can act on the same workflow step concurrently.

The engine uses PostgreSQL row-level locking via:

SELECT ... FOR UPDATE

to guarantee transactional consistency.

---

Database Schema Design

Separation Between Template and Runtime

The schema separates:

Layer	Purpose
workflow_template + workflow_step	reusable configuration
workflow_instance + workflow_instance_step	runtime transactional state

This allows workflow definitions to evolve independently from running workflow executions.

---

Polymorphic Workflow Entity Design

The workflow engine supports polymorphic entity references using:

(entity_type, entity_id)

This allows workflows to attach to:

• bookings
• units
• commission records
• future entities

without schema modifications.

---

Workflow Lifecycle

Example:

booking.cancellation_requested

1. System event fires
2. Active workflow template resolved
3. Workflow instance created
4. Runtime workflow steps generated
5. First step activated (awaiting_action)
6. Approver acts
7. Workflow advances or terminates
8. Audit log recorded

---

Runtime Step Snapshotting

Workflow instance steps snapshot assigned users/roles at instance creation time.

This prevents mid-workflow role changes from affecting historical workflow executions.

Example:

• User A was Sales Manager during workflow creation
• User role later changes
• Existing workflow remains historically consistent

---

Concurrency Strategy

The workflow engine prevents concurrent approvals using PostgreSQL row-level locking.

Approval/rejection flow:

1. Begin transaction
2. Lock workflow step row using SELECT ... FOR UPDATE
3. Validate step status is still awaiting_action
4. Apply approval/rejection atomically
5. Commit transaction

This guarantees:

• only one approver succeeds
• no double approvals
• no race conditions
• consistent workflow progression

If two approvers attempt approval simultaneously:

• first request succeeds
• second request receives descriptive error

---

Workflow Status Model

Workflow Instance Status

Status	Meaning
pending	created but not started
in_progress	currently processing
approved	fully approved
rejected	rejected by approver
cancelled	manually cancelled

---

Workflow Step Status

Status	Meaning
pending	waiting previous step
awaiting_action	active approver step
approved	approved
rejected	rejected

---

API Endpoints

Trigger Workflow

POST /api/v1/workflow/instances

Example:

{
  "event":"booking.cancellation_requested",
  "entity_type":"booking",
  "entity_id":2,
  "initiated_by":3
}

---

Get Workflow Instance

GET /api/v1/workflow/instances/{instanceID}

Returns:

• workflow instance
• runtime steps
• approvals/rejections
• comments
• timestamps

---

Get Workflow Template

GET /api/v1/workflow/templates/{templateID}

---

Pending Inbox

GET /api/v1/workflow/steps/pending?user_id=1

Returns all workflow steps awaiting approver action.

Supports:

• direct user assignments
• role-based assignments

---

Approve Workflow Step

POST /api/v1/workflow/steps/{stepID}/approve

Example:

{
  "acted_by_user_id":1,
  "comment":"Approved by sales manager"
}

---

Reject Workflow Step

POST /api/v1/workflow/steps/{stepID}/reject

Example:

{
  "acted_by_user_id":2,
  "comment":"Finance rejected request"
}

---

Audit Logging

All workflow decisions are written into immutable audit logs.

Audit entries capture:

• workflow instance
• workflow step
• action
• approver
• comment
• timestamp

This ensures traceability and compliance.

---

Assumptions

• Authentication and authorization are out of scope
• Notifications are represented using callback hooks
• Role resolution is abstracted behind an interface
• Sequential workflows are implemented
• Templates cannot be modified while active workflow instances exist

---

Seed Data

Seed migration includes:

• 2 projects
• 10 units
• 3 users
• 5 bookings
• sample workflow templates
• sample workflow steps
• sample workflow instance

---

Final Notes

This implementation focuses on:

• correctness
• transactional integrity
• clean architecture
• workflow extensibility
• concurrency safety