Database Schema
Relevant source files
The following files were used as context for generating this wiki page:
- packages/shared/src/types/supabase.types.ts
- packages/adapter-supabase/src/workflows/workflow-persistence.ts
- packages/adapter-supabase/src/nodes/node-persistence.ts
- packages/adapter-supabase/src/messages/message-persistence.ts
- packages/core/src/utils/persistence/README.md
- packages/shared/scripts/generate-db-types.ts
- packages/adapter-supabase/README.md
- packages/shared/src/types/mcp.types.ts
- packages/core/src/utils/persistence/memory/SupabaseStore.ts
The database is the persistence layer for the Lucky agentic workflow system, built on Supabase (PostgreSQL). It is designed to store and manage workflow definitions, track their evolutionary history, record every execution instance, and persist all associated data like inter-agent messages and performance metrics. The schema is version-centric, treating workflow configurations as immutable, evolvable data structures.
This document outlines the core tables, their relationships, and the processes for interacting with them. The schema is divided into logical groups for managing workflows, nodes (agents), executions, and the evolution process itself.
Schema Generation
TypeScript types for the database are automatically generated to ensure end-to-end type safety. A script uses the Supabase CLI to introspect the live database and generate type definition files for each schema.
This diagram illustrates the generation process for multiple schemas.
The script packages/shared/scripts/generate-db-types.ts is responsible for this process, targeting schemas such as public, iam, lockbox, app, and mcp.
Sources: packages/shared/scripts/generate-db-types.ts:12-18
Entity Relationship Diagram
The following diagram shows the primary tables and their relationships within the public schema, which forms the core of the workflow and evolution persistence.
Core Tables
Workflow & Versioning
These tables manage the core workflow definitions and their immutable, versioned configurations.
Workflow
Stores the base definition of a workflow.
| Column | Type | Description |
|---|---|---|
wf_id | text (PK) | The unique identifier for the workflow. |
description | text | A human-readable description of the workflow's purpose. |
clerk_id | text | The ID of the user who owns the workflow. |
name | text | The display name of the workflow. |
Sources: packages/core/src/utils/persistence/README.md:31-31, tests/helpers/test-auth-simple.ts:133-144
WorkflowVersion
This is a central table that stores each unique, immutable version of a workflow's configuration. It includes genealogy fields to track its evolutionary history.
| Column | Type | Description |
|---|---|---|
wf_version_id | text (PK) | A unique ID for the version, typically a SHA-256 hash of the configuration. |
workflow_id | text (FK) | Foreign key referencing Workflow.wf_id. |
dsl | jsonb | The JSON configuration (Directed Acyclic Graph) of the workflow. |
operation | text | The evolutionary operation that created this version (init, mutation, crossover, immigrant). |
parent1_id | text (FK) | A self-referencing key to the parent version (for mutation). |
parent2_id | text (FK) | A self-referencing key to the second parent (for crossover). |
generation_id | text (FK) | Foreign key referencing Generation.generation_id. |
commit_message | text | A description of the changes in this version. |
Sources: packages/core/src/utils/persistence/README.md:34-45, packages/adapter-supabase/README.md:167-177
Execution & Invocation
These tables record the runtime execution of workflows and their constituent nodes.
WorkflowInvocation
Represents a single execution of a specific WorkflowVersion.
| Column | Type | Description |
|---|---|---|
wf_invocation_id | text (PK) | A unique identifier for this specific run. |
wf_version_id | text (FK) | The WorkflowVersion that was executed. |
status | text | The execution status (running, completed, failed). |
workflow_io | jsonb | The initial input and final output data for the workflow. |
usd_cost | numeric | The total USD cost of the execution. |
fitness_score | numeric | The calculated fitness score from the evaluation. |
run_id | text (FK) | The EvolutionRun this invocation belongs to, if any. |
Sources: packages/core/src/utils/persistence/README.md:48-57, packages/adapter-supabase/README.md:179-192
NodeVersion
Stores the specific configuration of a node (agent) as part of a WorkflowVersion.
| Column | Type | Description |
|---|---|---|
node_version_id | text (PK) | Unique identifier for this version of the node. |
node_id | text | The node's ID within the workflow's DSL. |
wf_version_id | text (FK) | The WorkflowVersion this node configuration belongs to. |
system_prompt | text | The system prompt for the agent. |
tools | jsonb | A JSON array of the tools available to this node. |
llm_model | text | The language model used by the node (e.g., claude-3-5-sonnet-20241022). |
Sources: packages/core/src/utils/persistence/README.md:60-69, packages/adapter-supabase/README.md:194-205
NodeInvocation
Records the execution of a single node within a WorkflowInvocation.
| Column | Type | Description |
|---|---|---|
node_invocation_id | text (PK) | Unique identifier for the node's execution. |
node_id | text | The ID of the node that was invoked. |
wf_invocation_id | text (FK) | The parent WorkflowInvocation. |
summary | text | An AI-generated summary of the node's execution. |
large_summary | text | A more detailed summary of the execution. |
usd_cost | numeric | The cost incurred by this specific node invocation. |
status | text | The node's execution status (completed, failed). |
output | jsonb | The JSON output produced by the node. |
Sources: packages/core/src/utils/persistence/README.md:72-84, packages/adapter-supabase/README.md:207-219
Message
Logs the messages passed between nodes during a workflow invocation.
| Column | Type | Description |
|---|---|---|
msg_id | text (PK) | Unique identifier for the message. |
wf_invocation_id | text (FK) | The WorkflowInvocation this message belongs to. |
from_node_id | text | The ID of the node that sent the message. |
to_node_id | text | The ID of the node that received the message. |
payload | jsonb | The content of the message. |
role | text | The role of the message (user, assistant, system). |
Sources: packages/core/src/utils/persistence/README.md:160-172, packages/adapter-supabase/README.md:221-229
Evolution Tracking
These tables are dedicated to tracking the genetic programming and iterative improvement processes.
EvolutionRun
Represents a complete evolutionary process, such as a genetic programming run with multiple generations.
| Column | Type | Description |
|---|---|---|
run_id | text (PK) | Unique identifier for the evolution run. |
goal_text | text | The high-level goal of the optimization. |
config | jsonb | Configuration for the run (e.g., population size, generations). |
status | text | The status of the run (running, completed, failed). |
evolution_type | text | The type of evolution (gp, iterative). |
Sources: packages/adapter-supabase/README.md:233-242
Generation
Represents a single generation within an EvolutionRun.
| Column | Type | Description |
|---|---|---|
generation_id | text (PK) | Unique identifier for the generation. |
number | integer | The generation number (e.g., 1, 2, 3...). |
run_id | text (FK) | The parent EvolutionRun. |
best_workflow_version_id | text (FK) | The WorkflowVersion with the highest fitness in this generation. |
Sources: packages/adapter-supabase/README.md:244-252
MCP Schema
The mcp schema manages entities related to the Model Context Protocol, which allows the system to interact with external tools and servers. Type definitions for this schema are generated in packages/shared/src/types/mcp.types.ts.
Key tables include:
servers: Defines registered MCP servers, including metadata like display name, description, and repository URL.server_versions: Tracks different versions of an MCP server, their capabilities, and status.tools: Lists the tools exposed by each server version, including their input/output schemas and descriptions.user_server_configs: Stores user-specific configurations for connecting to MCP servers.
Sources: packages/shared/src/types/mcp.types.ts
Supabase Storage for Context
In addition to the relational database, the system uses Supabase Storage for persisting large context data associated with a workflow invocation. This is managed by the SupabaseContextStore.
Data is stored in a bucket (e.g., context) and organized into a directory structure based on the workflow invocation ID, scope, and key. Each entry consists of three files: the raw data, an AI-generated summary, and a metadata JSON file.
This diagram shows the file structure for a context entry.
This approach keeps the primary database lean while allowing for efficient storage and retrieval of large, unstructured or semi-structured data blobs.
Sources: packages/core/src/utils/persistence/memory/SupabaseStore.ts:13-14, 40-42, 90-104