Eddy as a Game Engine for Work

Last Updated: January 8, 2026

This document explores the metaphor of Eddy as a game engine. It's not just an analogy; it's a powerful mental model for understanding the system's architecture, its purpose, and the distinct roles of its users.

---

The Core Analogy: Mapping Eddy to Game Concepts

At its heart, a game consists of a world, players, rules, and a goal. Eddy's architecture maps to these concepts with surprising precision.

1. The Game Designer & The Level Editor

• The Game Designer: This is the Workflow Builder. They are the creative force, translating a desired experience (a business process) into a playable form.
• The Level Editor: The Workflow Builder UI is the designer's tool. The canvas for the BuilderStageGraph is the level map, and the PageBuilder is the tool for designing the "rooms" within that level.

2. The Game World & The Architecture

The static components of a workflow define the game world's structure, the literal "architecture" the players will navigate.

• The World Map: The workflow itself
• Locations / Rooms: Each page is a distinct location or room on the map
• Corridors & Locked Doors: page_transitions are the pathways between rooms. The transition.rule is the lock on the door, defining the conditions for passage
• Interactive Objects & Puzzles: blocks and sections are the objects within a room that players must interact with to proceed
• Character Classes & Abilities: workflow_roles are the character classes (e.g., "Approver," "Reviewer"). stage_role_assignments define the abilities of each class

3. The Players & The "Game Session"

• The Players: The users of the system
• The "Campaign" or "Quest": A workflow_run is a live instance of the game, a single playthrough of the campaign
• The Quest Log: The workflow_run_stages table acts as the quest log, tracking which locations have been visited and which objectives have been completed
• The Party Roster: session_role_assignments define the specific players who are part of this quest and which character class they are playing
• Player Turn & Location: session_assignments indicate whose turn it is and which room they are currently in

4. The Rules Engine

The most critical part of any game engine is that it impartially enforces the rules. In Eddy, this is the backend logic and the database itself. A player cannot move to a page they don't have access to. They cannot complete a stage without filling in required fields. The system is the infallible "Game Master," ensuring the game is played as designed.

---

The Nature of Data: Keys, Currency, and Trophies

Data serves multiple, crucial roles in this model.

Data as Keys

A piece of data entered by a player acts as a key to unlock a logical gate.

• A user selects "Approve" from a single-select block
• This writes a specific value to a cell in the sheet
• A page_transition rule checks for this value: IF sheet.status_column == 'Approve' THEN unlock path_A
• The data is the literal key that opens the door to the next stage

Data as Currency or Crafting Materials

Data can also be used as a resource.

• Data from one block (e.g., first_name) can be used by another block (e.g., a content block that says "Hello, {{first_name}}!")
• Data can be used in column formulas to calculate new values
• In advanced scenarios, data could be "spent" to trigger an external action via an automation

Data as the Trophy or High Score

The ultimate goal of the game is to produce a complete, valid row in the target sheet. This completed row is the trophy. It is the prize for winning the cooperative game.

Unlike a simple high score, this trophy has immense value outside the game. It is a structured, high-integrity asset that represents the successful completion of a business process.

---

Three Categories of Data: Fixtures, Quest Logs, and Player Input

When we look at Eddy's data architecture through the game engine lens, we can identify three distinct categories of data.

Category 1: Workflow-Level Fixtures (The Level Architecture)

These are the static, reusable definitions that define the structure of the game itself.

Tables & Structures:

• workflows - The game/campaign definition
• pages - Individual rooms or locations
• page_transitions - Corridors and pathways between rooms
• blocks - Interactive objects and UI elements within rooms
• sections - Containers that organize blocks
• workflow_roles - Character class definitions
• stage_role_assignments - The abilities each character class has in each room
• sheets and columns - The structure of the data to be collected

Characteristics:

• Immutable during gameplay: While a builder can edit these, they don't change during a session
• Shared across all sessions: The same workflow definition is used for hundreds or thousands of workflow runs
• Fetched once, cached aggressively: The builder needs all fixtures. A session viewer needs all fixtures for that workflow

Game Engine Analogy: These are the level design files, the asset packs, the game rules document.

Category 2: Session-Level Quest Logs (Progression State)

These are the dynamic, session-specific tracking structures that record where players are and what they've done.

Tables & Structures:

• workflow_runs - The active campaign instance
• workflow_run_stages - Which locations have been activated and completed
• session_role_assignments - Which specific users are playing which character classes
• session_assignments - Whose turn it is and which room they're in
• session_discussions - Communication between players during the quest

Characteristics:

• Mutable during gameplay: These update frequently as the session progresses
• Session-scoped: Each workflow run has its own independent quest log
• Read frequently, written less so: On each page load, we check progression state
• Lightweight: These tables are mostly IDs, timestamps, and foreign keys

Game Engine Analogy: This is the save game file. It's the data that lets you pick up where you left off.

Category 3: Player Input Data (Gameplay Actions & Results)

This is the actual data produced by players as they interact with the system.

Tables & Structures:

• cells - Individual data values entered by users
• rows - Complete records in a sheet (the "trophy")
• cell_versions - History of changes to data
• File uploads, linked records, and other rich data types

Characteristics:

• Created during gameplay: Users write this data as they complete blocks
• Persists after the quest: The completed row remains valuable long after the session ends
• High volume: A single session might create dozens or hundreds of cells
• The actual product: This is what the entire system exists to produce with high integrity

Game Engine Analogy: This is the gameplay itself—the actions taken, the score accumulated, the treasure collected.

---

Practical Implications for Data Fetching

This three-category model directly informs how different parts of the application should fetch data:

In the Builder

• Fetch: Category 1 (Fixtures) only
• Pattern: Single comprehensive fetch of all workflow structures
• Caching: Aggressive, invalidate only on explicit edits

In the Session View

• Fetch: All three categories
• Pattern: Fixtures once, quest logs on mount/invalidation, player data lazily
• Caching: Fixtures aggressive, quest logs moderate, player data as needed

In the Sheet View

• Fetch: Category 1 (structure) + Category 3 (data)
• Pattern: Fetch sheet structure, then fetch all rows/cells
• Caching: Structure aggressive, data moderate with real-time updates

---

Why This Metaphor Matters

The game engine metaphor is powerful because:

1. It's intuitive: Everyone understands games. The concepts of levels, players, rules, and goals are universal.

2. It clarifies roles: Builders are designers, users are players, the system is the game master.

3. It guides architecture: The three categories of data map directly to how we structure queries and optimize performance.

4. It reveals possibilities: Thinking of Eddy as a game engine opens up new features: achievements, leaderboards, difficulty levels, etc.

5. It explains value: The "trophy" (completed row) is the tangible output of the "game" (workflow session).

---

Related Documentation