Workflows

Workflow engine for managing renovation project phases and tasks. Template-based system where workflow templates define a sequence of phases and tasks; a state machine governs transitions; and a rules engine enables automatic progression.

Source Files

Layer	Path
Schema	backend/src/db/schema.ts
Routes	backend/src/routes/workflow/ (tasks, phases, templates, deals, appointments, activities)
Task Service	backend/src/services/task-service.ts
State Machine	backend/src/services/workflow-state-machine.ts
Config Service	backend/src/services/workflow-config-service.ts
Template Service	backend/src/services/workflow-template-service.ts
Page	frontend/src/pages/internal/WorkflowPage.tsx
Components	frontend/src/components/workflow/ (5+ files)
Store	frontend/src/store/workflow.ts (Zustand)

Database Tables

Table	Purpose
workflowTemplates	Reusable workflow definitions (name, description, project type)
workflowTemplatePhases	Phases within a template (order, name, entry/exit criteria)
workflowTemplatePhaseTasks	Tasks within a phase (order, type, assignee rules, checklist)
workflowTemplateVersions	Version history for templates (immutable snapshots)
workflowChecklistTemplates	Reusable checklist definitions attached to tasks
workflowTaskTypes	Enumeration of task types (e.g., inspection, document collection, approval)
workflowRules	Automation rules for transitions (conditions and actions)
workflowTransitionLog	Audit trail of state transitions (from, to, trigger, timestamp)
taskTimeBookings	Time tracking entries per task

Architecture

State Machine

workflow-state-machine.ts governs all phase and task transitions:

• Phases progress linearly with configurable entry/exit criteria
• Tasks within a phase can run in parallel or sequentially
• Transitions are validated against the current state and rules before execution
• Every transition is logged in workflowTransitionLog

Template Versioning

Templates are versioned via workflowTemplateVersions. When a template is modified, a new version snapshot is created. Active projects continue using the version they were started with — updates only affect new projects.

Rules Engine

workflowRules define automatic transitions:

Rule Component	Purpose
Condition	When to fire (e.g., all tasks in phase complete)
Action	What to do (e.g., advance to next phase, notify user)
Priority	Execution order when multiple rules match

Key Features

• Phase/task hierarchy — templates define phases; phases contain tasks; tasks have checklists
• Time booking — staff log time against tasks via taskTimeBookings
• Activity tracking — all workflow interactions recorded for audit
• Template management — admins create and version templates in Admin Dashboard
• Checklist templates — reusable checklists attached to task types

Frontend State

The workflow UI uses a Zustand store at frontend/src/store/workflow.ts for:

• Current workflow instance and active phase/task
• Task status updates and optimistic mutations
• Filter and view state (Kanban vs. list)

Relationships

WorkflowTemplate 1──* Phases 1──* Tasks
WorkflowTemplate 1──* Versions
Task *──1 WorkflowTaskType
Task 1──* TaskTimeBookings
Task *──1 Users (assignee)
Project *──1 WorkflowTemplate (active workflow)
Task ──> Appointments
Task ──> Quotes

Related Pages

Projects | Users | Appointments | Quotes | Departments | Admin Dashboard | Service Layer Pattern | Database Architecture