DEV Community

Chris Lloyd Fallaria
Chris Lloyd Fallaria

Posted on

How I Built a Multi-Department Workflow Routing System in Laravel with Inertia.js

#laravel #php #webdev #inertia

The Problem I Was Trying to Solve

When I started building VMMS — a voucher management system
for government offices — one of the hardest parts wasn't
the UI or the database schema.

It was the workflow routing.

A voucher request doesn't just go to one office. It goes
to multiple departments in a specific order — each one
needs to process it before passing it to the next.

And at any point, a department can:

  • Complete their step and pass it forward
  • Reject the entire request
  • Flag it for missing documents and pause processing

I needed a system that could handle all of that cleanly.

How I Modeled It

Every voucher type has a configurable processing flow
stored in a transaction_flows table:

Schema::create('transaction_flows', function (Blueprint $table) {
    $table->id();
    $table->foreignId('voucher_id')->constrained()->cascadeOnDelete();
    $table->string('department');
    $table->integer('order_number');
    $table->timestamps();
});
Enter fullscreen mode Exit fullscreen mode

When a client submits a request, the system reads the
flow for that voucher type and routes it to the first
department automatically.

Tracking Progress with Audit Trails

Every time a department processes a request, an audit
trail record is created:

Schema::create('audit_trails', function (Blueprint $table) {
    $table->id();
    $table->foreignId('transaction_id')->constrained()->cascadeOnDelete();
    $table->string('processing_offices');
    $table->timestamp('process_initiate')->nullable();
    $table->timestamp('process_accomplished')->nullable();
    $table->date('deadline')->nullable();
    $table->timestamps();
});
Enter fullscreen mode Exit fullscreen mode

process_initiate is set when a department starts
processing. process_accomplished is set when they
finish. If only process_initiate is set — that's
the currently active department.

Finding the Current Department

This was trickier than I expected. Here's the logic:

$activeAudit = $auditTrails->first(
    fn($a) => $a->process_initiate && !$a->process_accomplished
);

if ($activeAudit) {
    return $activeAudit->processing_offices;
}

// If no active audit, find the next step
$doneOrders = $auditTrails
    ->filter(fn($a) => $a->process_accomplished)
    ->map(fn($a) => $flow->firstWhere('department', $a->processing_offices)?->order_number ?? 0);

$lastDone = $doneOrders->max() ?? 0;
$nextStep = $flow->firstWhere('order_number', $lastDone + 1);

return $nextStep?->department ?? 'Completed';
Enter fullscreen mode Exit fullscreen mode

The tricky part was handling edge cases:

  • What if a department is skipped?
  • What if a request is returned for missing documents?
  • What if the last department just finished?

Each of these needed its own handling.

The Pipeline Stepper on the Frontend

On the Vue 3 side, I built a stepper component that
shows each department as a step — green for done,
pulsing for active, grey for pending.

const stepStatus = (req, step, stepIndex) => {
    const audits = req.audit_trails ?? [];
    const accomplishedCount = audits.filter(
        a => a.process_accomplished !== null
    ).length;

    if (stepIndex < accomplishedCount)  return 'done';
    if (stepIndex === accomplishedCount) return 'active';
    return 'pending';
};
Enter fullscreen mode Exit fullscreen mode

Simple logic but it took a few rewrites to handle
all the edge cases correctly.

Missing Documents — Pausing the Flow

When a staff member flags a request for missing
documents, the flow pauses. The client gets notified
and needs to upload the corrected files before
processing can continue.

I handled this through a separate requirement_validations
table that tracks which transactions are waiting for
documents from which user.

$missingDocIds = RequirementValidation::where('receiver_id', $userId)
    ->whereNull('resume_transaction')
    ->pluck('transaction_id')
    ->toArray();
Enter fullscreen mode Exit fullscreen mode

When resume_transaction is filled — the flow resumes
and the request goes back to the staff for continued
processing.

What I Learned

1. Model the flow separately from the transaction
Keeping transaction_flows separate from
voucher_transactions made it easy to change
the processing order for a voucher type without
affecting existing requests.

2. Audit trails are your best friend
Storing every processing event with timestamps
made it easy to calculate processing times,
track performance, and build analytics on top.

3. Edge cases will get you
The "happy path" was easy. Missing documents,
skipped departments, and rejected requests
all needed separate handling. Budget time for this.

The Result

The pipeline tracker is now one of the most useful
features in VMMS. Clients can see exactly where
their request is in real time — no more following
up in person.

If you want to see it in action:

🔴 Live demo: https://vmms-app-production.up.railway.app/login

VMMS is available on Gumroad if you want to use it
or build on top of it:
👉 https://getvmms.gumroad.com/l/zeroqz

Happy to answer any questions in the comments!

Top comments (0)