Process Intelligence Architecture

Source: This page is based on docs/PROPOSALS/PROCESS_INTELLIGENCE.md

Last Updated: January 16, 2026

This document outlines the key metrics, insights, and reports that can be surfaced to builders and administrators to analyze and improve workflows. Process Intelligence in Project Eddy is divided into two primary contexts: intelligence for a single, specific session, and aggregated intelligence across all sessions of a given workflow.

1. Single Session Intelligence

This level of intelligence provides a detailed, granular view of a single workflow_run. It's designed for troubleshooting, auditing a specific instance, and understanding the "story" of one execution.

Core Timing Metrics

Total Cycle Time

What it is: The total time elapsed from the start to the completion of the session
Calculation: workflow_runs.completed_at - workflow_runs.created_at

Stage Duration

What it is: The time spent actively working on a single stage
Calculation: For a given workflow_run_stage, calculate completed_at - active_at

Handoff / Idle Time

What it is: The time elapsed between the completion of one stage and the activation of the next
Why it's valuable: Identifies delays caused by communication gaps, notification latency, or participants not being ready
Calculation: workflow_run_stages(target).active_at - workflow_run_stages(source).completed_at

Execution Analysis

Execution Path

What it is: A visual representation of the specific path taken through the workflow graph
Implementation: In the Session Graph UI, highlight the nodes and edges corresponding to completed workflow_run_stages

Participant Timeline

What it is: A Gantt-style chart showing which user was assigned to which stage and for how long
Calculation: Uses session_assignments to link assignee_id to workflow_run_stages

Session Audit Log

What it is: A human-readable, chronological list of key events that occurred during the session
Calculation: Query the events table for all records where workflow_run_id matches the current session

2. Aggregated Intelligence

This level of intelligence provides a high-level, analytical view by aggregating data from all workflow_run instances for a given workflow. It is designed to help builders and administrators identify trends, find systemic bottlenecks, and make data-driven decisions.

Standalone Process Metrics

Cycle Time Analysis

What it is: Statistical analysis of the total time taken for all completed runs
Metrics: Average, Median, and 95th Percentile (P95) cycle times
Why P95 matters: Crucial for understanding the worst-case performance, which is often tied to user experience
Calculation: Aggregate (completed_at - created_at) from all workflow_runs for the workflow_id

Bottleneck Analysis

What it is: Identifies which stages consistently take the most time
Metrics:
- Avg. Stage Duration: For each page_id, average (completed_at - active_at) across all associated workflow_run_stages
- Avg. Handoff Time: For each transition, average the time between the source stage's completion and the target stage's activation

Workload Distribution

What it is: A breakdown of how many stages have been completed by each user or role
Why it's valuable: Helps managers understand team workload, identify individuals who may be overloaded, and rebalance assignments
Calculation: Count completed workflow_run_stages and group by completed_by or assigned role

Standalone Business Metrics

Path Frequency Analysis

What it is: For workflows with conditional branches, this shows the percentage of runs that go down each path
Why it's valuable: Reveals the most common outcomes. For an approval process, this would instantly show the ratio of "Approved" vs. "Rejected" runs
Calculation: Query the cells table for the relevant column_id across all rows and calculate the distribution of values

Rework & Loop Analysis

What it is: Counts the average number of times a session passes through a loop in the workflow
Why it's valuable: High rework rates can indicate unclear instructions, poor input data quality, or systemic issues
Calculation: Track when a workflow_run_stage is re-activated via the events table

Correlated Intelligence: Blending Process & Business Data

This is the most powerful form of intelligence, where business data from cells is used to segment and analyze the process metadata.

Outcome-Driven Performance Analysis

What it is: A report that compares the average cycle time based on the final outcome of the workflow
Example: "Does it take longer for us to reject a request than to approve it?"
Calculation: Join workflow_runs with rows and cells. For the column_id that stores the final outcome, GROUP BY the cell.value and calculate the average cycle time for each group

Data-Segmented Bottleneck Analysis

What it is: A breakdown of average stage duration, segmented by an input value from an earlier stage
Example: "Does the 'Legal Review' stage take longer for contracts from the 'EMEA' region vs. 'NA'?"
Calculation: Join workflow_run_stages with rows and cells. Filter for a specific page_id (the bottleneck stage), then GROUP BY the cell.value of interest

Participant Performance by Work Context

What it is: An analysis of how quickly different users or roles complete tasks, segmented by the nature of the task itself
Example: "Alice is slower on 'Enterprise' tier support tickets but much faster on 'SMB' tickets"
Why it's valuable: Provides a fairer view of performance and can inform workload routing and training opportunities

Value-Based Path Analysis

What it is: A report showing the distribution of business value across different workflow paths
Example: "What is the total contract value of all deals that went through the 'Expedited Legal Review' path versus the standard path?"
Calculation: Join user_transitions with rows and cells. For a specific transition or path, sum the values from a monetary column_id

3. Visualization & Presentation

To be effective, this intelligence must be presented in an intuitive way.

The Interactive Intelligence Dashboard

A dedicated page for each workflow that summarizes key metrics. The most powerful feature would be a "Group By" dropdown on charts.

Example: For a chart showing "Average Stage Duration," this dropdown would be dynamically populated with the columns from the workflow's sheet (e.g., "Region," "Deal Size," "Priority"). This allows an admin to instantly generate correlated intelligence reports on the fly.

Graph Overlays

In the workflow builder, allow the user to toggle an "Analytics Overlay" on the graph. This could display:

The average stage duration directly on each node
The average handoff time on each edge
Instantly visualizing bottlenecks

Individual Session View

The single session intelligence should be available as a tab or modal when viewing a specific workflow_run's history.

4. Future Directions

Building on this foundation, more advanced intelligence can be developed.

Predictive Analytics

Based on historical data, predict:

The completion time of an in-flight session
The likelihood of a specific outcome, given its early input data

Backend:
- Create /api/workflow_runs/:id/intelligence endpoint
- Calculate timing metrics (cycle time, stage durations, handoff times)
- Generate execution path data
Frontend:
- Add "Intelligence" tab to session view
- Display timing metrics in cards
- Render execution path visualization
- Show participant timeline as Gantt chart

Part 2: Aggregated Workflow View

Priority: Medium

Backend:
- Create /api/workflows/:id/intelligence endpoint
- Calculate aggregated metrics (avg/median/P95 cycle times)
- Identify bottlenecks (avg stage durations)
- Generate path frequency analysis
Frontend:
- Add "Analytics" tab to workflow builder
- Display key metrics dashboard
- Render bottleneck visualization on graph
- Show path frequency charts

6. The "Process Intelligence Report" Concept

1. The Aggregated Workflow Report

A comprehensive PDF/HTML report that can be generated for any workflow, showing:

Summary statistics (total runs, completion rate, avg cycle time)
Bottleneck analysis with charts
Path frequency distribution
Workload distribution by user/role

2. The Single Session Report

A detailed audit report for a specific session, showing:

Timeline of events
Participant involvement
Data collected at each stage
Execution path taken

A modal that displays all the data collected during a session in a hierarchical, easy-to-read format.

Session Architecture

Understanding session structure

Database Schema

Data model for analytics

Process Intelligence