Aecendt Global — Sharetribe Hiring Marketplace with Custom Workflow Intelligence Module

Aecendt Global is a two-sided hiring marketplace built on Sharetribe Web Template. Dr. Michelle Thomas of MST Innovative Tech came to us with a marketplace already running — but she needed something no off-the-shelf Sharetribe extension could deliver: a post-hire workflow automation engine that would turn every successful hire into a structured onboarding, training, compliance, and performance workflow, all visible in a real-time role-aware dashboard.

We designed and built the Workflow Intelligence Module entirely inside the existing Sharetribe codebase — no separate app, no new infrastructure — using Supabase as the data layer, node-cron for background automation, SendGrid for notifications, and React 18 for the six new dashboard pages. The result is a marketplace that doesn't just connect employers and candidates. It manages what happens after the hire.

Building Inside an Existing Codebase Without Breaking It

Aecendt was already live with real users. Every addition had to integrate seamlessly with the existing Node.js/Express server, the existing Sharetribe authentication flow, and the existing React routing — without disrupting any live functionality. There was no greenfield freedom here.

Detecting the Hire Event Reliably

Sharetribe doesn't push an "employee hired" webhook. The platform uses a transaction state machine, and the hire confirmation maps to a job-application-accepted transition that can fire across two different transition paths. Building a poller that catches both paths, deduplicates events, and launches the correct onboarding blueprint without double-firing required careful state analysis of the existing transaction model.

13 New Database Tables with Zero Data Model Conflicts

The existing Supabase schema had 3 tables. We added 13 more — blueprints, blueprint stages, stage tasks, workflow instances, stage instances, task completions, evaluations, evaluation scores, workforce events, employee timeline, exceptions, organizations, employees — all with foreign key constraints, indexes, and role-based check constraints that enforced data integrity without touching the original schema.

Role-Aware Dashboards Across 5 User Types

The dashboard had to show different views to HR Admins, Managers, Department Managers, Employees, and Mentors — pulling from the same data model but filtering and presenting entirely different subsets. The Sharetribe identity bridge (user UUID → employee/organization mapping) had to be established at login time and threaded through every downstream API call.

9 Task Types in a Single Unified UI

The Blueprint Builder needed to support 9 different task types — Documents, Videos, Policies, Acknowledgements, Forms, Evaluation Scorecards, Approvals, Notes, and Training — each with different required fields, different completion flows, and different verification logic. Collapsing this into a single composable task form without a confusing UI was a significant design challenge.

Module-Inside-the-Monolith Architecture

Rather than extracting the workflow engine into a microservice, we added it as a discrete module inside the existing Node.js/Express server. All 20+ new API routes are grouped under /api/workflow/ in server/apiRouter.js. All six new React pages use the existing loadable component pattern and are registered in the existing routeConfiguration.js. Existing code paths are untouched — the module simply coexists.

Event Poller with Deduplication

We wrote server/api/cron/workflowEventPoller.js — a node-cron job firing every 5 minutes that queries the Sharetribe Integration API for recent transaction transitions. It filters for job-application-accepted events, checks the workforce_events table for prior processing, and auto-launches the matching blueprint for the organization. The deduplication key is transaction_id + event_type — safe against both double-fires and server restarts.

Supabase Data Layer with Full Migration Control

All 13 new tables were defined in server/supabase/workflow/migration.sql — a single idempotent migration script with all indexes, check constraints, and foreign keys. Table access is handled through three service modules (blueprints.js, instances.js, events.js) that expose clean CRUD helpers to the API handlers. No raw SQL in route handlers.

Sharetribe Identity Bridge

Every Sharetribe user has a UUID. Our bridge stores the mapping between that UUID and the Supabase employees table at the API level — every workflow operation is scoped to organizationId derived from the logged-in user's Sharetribe session. There's no separate login, no separate session — the existing Sharetribe auth context flows through to every workflow API call.

Unified Workflow Shell with Dark Sidebar

All six workflow pages — Dashboard, Blueprint Builder, Learning & Certifications, Performance Reviews, Compliance, Mentoring — share a single WorkflowLayout shell component with a 220px dark sidebar. Navigation, role detection, and layout are handled once in the shell. Individual pages focus purely on their domain logic. The /workflow root route redirects to /workflow/dashboard automatically.

Drag-to-Reorder + Bidirectional Document Upload

The Blueprint Builder uses HTML5 drag events with optimistic local state for instant task reordering — the PUT /api/workflow/stages/:id/tasks/reorder call fires in the background. Document upload reuses the existing /api/upload-pdf endpoint that writes to Supabase Storage — admins attach reference documents to tasks at design time, and employees upload completion evidence at runtime. Both files are visible inline in the task row.

7-Event SendGrid Notification System

server/api/workflow/notifications.js wraps SendGrid for seven workflow trigger points: blueprint launched, task assigned, deadline approaching (48h), task overdue, stage completed, certification issued, and workflow completed. It fetches each user's email via the Sharetribe Integration SDK — no separate user table needed.

Delivered in 3 Milestones — M4 Analytics Underway

• M1 — Data model + Blueprint Builder API + UI (13 tables, 20+ routes, full CRUD)
• M2 — Automation engine: hire event poller, deadline checker, 7-event SendGrid notifications
• M3 — All four post-hire modules: Learning & Certifications, Performance Reviews, Compliance, Mentoring
• M3+ — Unified workflow shell, form validation, task assignment by role, drag-to-reorder, bidirectional document upload
• M4 — Analytics dashboard and event architecture (in progress)

Zero Disruption to the Live Marketplace

Every milestone was delivered to the Heroku staging environment (aecendt-dev-3917f79fcc31.herokuapp.com) without breaking any existing marketplace functionality. The hire event poller has been running in production across both job-application-accepted transition paths with zero double-fires observed.

Platform Scale

• 13 new Supabase tables with full relational integrity and composite indexes
• 20+ new API endpoints organized under a single workflow namespace
• 6 new React pages with role-aware rendering (HR Admin, Manager, Department Manager, Employee, Mentor)
• 2 background cron jobs: 5-minute hire event poller + daily 8am deadline checker
• 9 task types supported in a single composable Blueprint Builder UI
• Bidirectional document upload: admin reference docs + employee completion evidence per task

Architecture that Survives a Sharetribe Migration

The Supabase data layer is fully decoupled from Sharetribe's internal models. The identity bridge maps UUIDs — when Dr. Thomas eventually migrates off Sharetribe, the entire Workflow Intelligence Module migrates with zero data changes. This was an explicit design requirement from the client, and we built for it from day one.

Technical Architecture

Stack Overview

• Base marketplace: Sharetribe Web Template v8.3.2 (React 18 + Node.js/Express)
• Workflow data layer: Supabase (PostgreSQL) — 13 new tables, clean migration script
• Background automation: node-cron — hire event poller (5min) + deadline checker (daily 8am)
• Notifications: SendGrid — 7 workflow trigger events, email fetched via Sharetribe Integration SDK
• Calendar & Video: Nylas + Zoom (existing integrations extended to workflow task types)
• Search: Algolia (existing marketplace search, untouched)
• Payments: Stripe subscriptions (existing marketplace billing)

Blueprint Builder

The Blueprint Builder is the heart of the workflow engine. HR Admins design reusable workflow templates — called Blueprints — that define the sequence of stages and tasks every employee goes through after being hired for a specific role or department. Each Blueprint supports:

• Unlimited stages (Onboarding, Training, 30-Day Review, Compliance Renewal, Exit, etc.)
• 9 task types per stage: Document, Video, Policy, Acknowledgement, Form, Evaluation Scorecard, Approval, Note, Training
• Role assignment per task (any / employee / hr_admin / manager / department_manager)
• Required vs optional flag per task
• Reference document attachment per task (admin uploads a PDF; employee sees it when completing)
• Drag-to-reorder tasks within a stage via HTML5 drag events with optimistic UI

Automation Engine

Two cron jobs drive the automation layer:

• workflowEventPoller — runs every 5 minutes, queries Sharetribe Integration API for job-application-accepted transitions, cross-references workforce_events for deduplication, auto-launches the matching Blueprint for the organization
• workflowDeadlineChecker — runs daily at 8am UTC, marks tasks overdue, flags manager bottlenecks (3+ days without action), sends 48-hour due-soon reminder emails via SendGrid

Live Dashboard

The Workflow Dashboard is role-aware at the component level:

• HR Admin view: full employee grid, workflow health indicators, exception flags, overdue task count per employee
• Manager view: employees in their department only, pending approvals, manager bottleneck alerts
• Employee view: My Tasks panel (filtered by their role assignment), current stage progress, upcoming deadlines

Post-Hire Modules (M3)

• Learning & Certifications — HR issues certificates (title, issued date, expiry date); system tracks expiry and flags renewals
• Performance Reviews — weighted-average scoring across configurable criteria (score 1–5 per criterion, auto-weighted average); reviewable by manager
• Compliance — policy acknowledgements with document upload; overdue tracking when acknowledgement window expires
• Mentoring — mentor assignment by Sharetribe UUID; activity log with title + notes per session; mentee dashboard visible to both parties

Database Design Decisions

• All 13 tables added in a single idempotent migration.sql — runs cleanly against any fresh Supabase project
• Identity bridge: employees.sharetribe_uuid is the only coupling point to Sharetribe — everything else is internal to the workflow schema
• assigned_to_role on stage_tasks uses a PostgreSQL CHECK constraint — invalid role values are rejected at the database level, not just the application level
• evaluation_scores stores criteria and scores as rows, not JSON — queryable, aggregatable, and auditable
• workforce_events acts as both the event dedup table and the audit trail — every automation action is recorded with a timestamp and payload