Assignment System Architecture

Source: This page is based on docs/ASSIGNMENTS.md

Last Updated: October 18, 2023

This document provides a developer-focused overview of the Assignment System in Project Eddy. It covers the core concepts, data models, and runtime logic that govern how work is assigned to users within a workflow.

High-Level Overview: The "Who, What, When" of Work

At its core, Eddy is a "game engine for work." The assignment system is the set of rules that defines the players, their abilities, and whose turn it is to act. It's designed to answer three critical questions for any collaborative process:

Who can do the work? This is managed by defining abstract Roles and then "casting" specific Users into those roles for each session.
What can they do? This is controlled by Permissions that specify which roles can view, edit, or complete each stage of a workflow.
When is it their turn? This is handled dynamically at runtime, creating actionable Tasks for users only when a stage they are responsible for becomes active.

This system separates the design of a process from its execution, allowing for flexible, powerful, and clear management of multi-user workflows.

Core Concepts & Data Models

The assignment system is built upon four key database tables that work together.

A. The Abstract Role (`workflow_roles`)

This is the "character class" in the game. It's a template for a type of participant, defined once at the workflow level.

Purpose: To represent an abstract role within a process (e.g., "Submitter," "Manager," "Client," "Approver")
Scope: Defined per workflow
Key Attributes: name, description, color

A workflow_role doesn't know about specific users; it's a reusable definition of a participant type.

B. The Permission Template (`stage_role_assignments`)

This defines the "abilities" of each character class on each "level" of the game. It links an abstract role to a specific page (stage) and defines what that role is allowed to do there.

Purpose: To grant permissions to roles for specific stages
Scope: Links a workflow_role to a page
Key Attributes:
- can_write: Controls whether the role can edit data on the stage. If false, the stage is read-only for that user.
- can_progress: Controls whether the role can complete the stage and advance the workflow.

This is the static permission model defined by the workflow builder.

C. The "Casting Call" (`session_role_assignments`)

This is where abstract roles meet real people for a specific "playthrough" of the game. When a session (a workflow_run) begins, users are assigned to the roles defined in the workflow.

Purpose: To assign a specific user to a workflow_role for the duration of a single workflow_run
Scope: Links a user to a workflow_role for one workflow_run
Example: "For this specific onboarding session (run #123), Alice is the 'Manager' and Bob is the 'Submitter'."

This record provides the context needed to determine which person is responsible for a role's duties during a live session.

D. The Actionable Task (`session_assignments`)

This is the most granular and dynamic piece of the system. A session_assignment is the actual task that appears in a user's "to-do" list. It is created automatically by the system when a stage becomes active.

Purpose: To link a specific user to a specific, active stage in a session, granting them access and creating an actionable task
Scope: Links a user to a workflow_run_stage
Creation: Generated dynamically when a stage's active_at field is populated
Function: This record is what powers the "Your Assignments" dashboard

The Assignment Lifecycle: From Design to Execution

Here is how the four concepts work together in practice:

1. Design Time (in the Workflow Builder)

A builder creates a workflow_role called "Reviewer"
The builder adds a page called "Final Check"
The builder creates a stage_role_assignment linking the "Reviewer" role to the "Final Check" page, granting them can_write: true and can_progress: true

2. Run Time (a new Session is created)

A manager starts a new workflow run
The manager creates a session_role_assignment to cast a specific user, Carol, into the "Reviewer" role for this run

3. Progression (the Session is in progress)

The workflow progresses until the "Final Check" stage is reached
The system sets the active_at timestamp on the corresponding workflow_run_stage record
This triggers the assignment logic:
- The system looks up the stage_role_assignments for "Final Check" and sees the "Reviewer" role is required
- It then looks up the session_role_assignments for this run and sees that Carol is the "Reviewer"
- It automatically creates a new session_assignment record, linking Carol to the active "Final Check" stage
Carol now sees "Final Check" in her assignment list and receives a notification

Advanced Assignment Types

The core logic above is extended to handle automated workflow starts.

Scheduled Start Assignments

Table: scheduled_start_assignments
Purpose: To pre-assign users to roles for workflows that run on a recurring schedule
Usage: When the scheduler automatically creates a new workflow_run, it uses these records to create the initial session_role_assignments

Self-Service Start Assignments

Table: self_service_assignments
Purpose: To define default or required participants for workflows that can be started by anyone via a public link
Usage: This ensures that even if a customer initiates a process, the correct internal team members are automatically assigned to their roles

Summary of Key Tables

Table Name	Purpose	When Created	Analogy
`workflow_roles`	Defines an abstract participant type	Design Time (Builder)	The Character Class
`stage_role_assignments`	Defines permissions for a role on a specific stage	Design Time (Builder)	The Ability List
`session_role_assignments`	Assigns a real user to a role for one session	Run Time (Session Start)	The Party Roster / Casting
`session_assignments`	The live, actionable task for a user on a stage	Run Time (Stage Activation)	The "Your Turn" Notification

Architectural Limits & Challenges

While the current assignment system is robust, its architecture presents several challenges when considering more complex or dynamic use cases.

The "Stuck" Workflow: The Blocked Handover Problem

Scenario: A workflow progresses to a stage that requires the "Legal" role, but no user has been assigned to that role in the session_role_assignments for this specific run.

Result: The workflow cannot create a session_assignment and therefore comes to a halt. It is "stuck" until a session administrator manually intervenes.

Challenge: This requires robust error handling, clear notifications to the right people, and a user-friendly interface for resolving these deadlocks.

Dynamic Assignments: Mid-Flight Changes

The model is optimized for assigning roles at the start of a session. It becomes more complex when dealing with changes during a live workflow run.

Challenges:

Reassigning a role mid-session
Adding new participants dynamically
Handling role changes when a stage is already active

Complex Assignment Logic: Beyond "Any User in Role"

The current system assigns all users in a role to a stage. More complex patterns might be needed:

Round-robin: Distribute work evenly across users in a role
Load balancing: Assign to the user with the fewest active tasks
Skill-based routing: Assign based on user attributes or expertise
Escalation: Automatically reassign if a task isn't completed within a timeframe