5 changed files with 459 additions and 0 deletions
--- a/docs/database_entities.md
+++ b/docs/database_entities.md
@@ -0,0 +1,303 @@
+# Database Entities Documentation
+
+This document describes the core entities in the USDA Vision database schema, focusing on entity-specific attributes (excluding generic fields like `id`, `created_at`, `updated_at`, `created_by`).
+
+## Entity Relationships Overview
+
+```
+Experiment Phase (Template)
+    ↓
+Experiment
+    ↓
+Experiment Repetition
+    ↓
+Experiment Phase Execution (Soaking, Airdrying, Cracking, Shelling)
+```
+
+---
+
+## 1. Experiment Phase
+
+**Table:** `experiment_phases`
+
+**Purpose:** Defines a template/blueprint for experiments that specifies which processing phases are included and their configuration.
+
+### Attributes
+
+- **name** (TEXT, UNIQUE, NOT NULL)
+  - Unique name identifying the experiment phase template
+  - Example: "Phase 2 - Standard Processing"
+
+- **description** (TEXT, nullable)
+  - Optional description providing details about the experiment phase
+
+- **has_soaking** (BOOLEAN, NOT NULL, DEFAULT false)
+  - Indicates whether soaking phase is included in experiments using this template
+
+- **has_airdrying** (BOOLEAN, NOT NULL, DEFAULT false)
+  - Indicates whether airdrying phase is included in experiments using this template
+
+- **has_cracking** (BOOLEAN, NOT NULL, DEFAULT false)
+  - Indicates whether cracking phase is included in experiments using this template
+
+- **has_shelling** (BOOLEAN, NOT NULL, DEFAULT false)
+  - Indicates whether shelling phase is included in experiments using this template
+
+- **cracking_machine_type_id** (UUID, nullable)
+  - References the machine type to be used for cracking (required if `has_cracking` is true)
+  - Links to `machine_types` table
+
+### Constraints
+
+- At least one phase (soaking, airdrying, cracking, or shelling) must be enabled
+- If `has_cracking` is true, `cracking_machine_type_id` must be provided
+
+---
+
+## 2. Experiment
+
+**Table:** `experiments`
+
+**Purpose:** Defines an experiment blueprint that specifies the parameters and requirements for conducting pecan processing experiments.
+
+### Attributes
+
+- **experiment_number** (INTEGER, NOT NULL)
+  - Unique number identifying the experiment
+  - Combined with `phase_id` must be unique
+
+- **reps_required** (INTEGER, NOT NULL, CHECK > 0)
+  - Number of repetitions required for this experiment
+  - Must be greater than zero
+
+- **weight_per_repetition_lbs** (DOUBLE PRECISION, NOT NULL, DEFAULT 5.0, CHECK > 0)
+  - Weight in pounds required for each repetition of the experiment
+
+- **results_status** (TEXT, NOT NULL, DEFAULT 'valid', CHECK IN ('valid', 'invalid'))
+  - Status indicating whether the experiment results are considered valid or invalid
+
+- **completion_status** (BOOLEAN, NOT NULL, DEFAULT false)
+  - Indicates whether the experiment has been completed
+
+- **phase_id** (UUID, NOT NULL)
+  - References the experiment phase template this experiment belongs to
+  - Links to `experiment_phases` table
+
+### Constraints
+
+- Combination of `experiment_number` and `phase_id` must be unique
+
+---
+
+## 3. Experiment Repetition
+
+**Table:** `experiment_repetitions`
+
+**Purpose:** Represents a single execution instance of an experiment that can be scheduled and tracked.
+
+### Attributes
+
+- **experiment_id** (UUID, NOT NULL)
+  - References the parent experiment blueprint
+  - Links to `experiments` table
+
+- **repetition_number** (INTEGER, NOT NULL, CHECK > 0)
+  - Sequential number identifying this repetition within the experiment
+  - Must be unique per experiment
+
+- **scheduled_date** (TIMESTAMP WITH TIME ZONE, nullable)
+  - Date and time when the repetition is scheduled to be executed
+
+- **status** (TEXT, NOT NULL, DEFAULT 'pending', CHECK IN ('pending', 'in_progress', 'completed', 'cancelled'))
+  - Current status of the repetition execution
+  - Values: `pending`, `in_progress`, `completed`, `cancelled`
+
+### Constraints
+
+- Combination of `experiment_id` and `repetition_number` must be unique
+
+---
+
+## 4. Experiment Phase Executions
+
+**Table:** `experiment_phase_executions`
+
+**Purpose:** Unified table storing execution data for all phase types (soaking, airdrying, cracking, shelling) associated with experiment repetitions.
+
+### Common Attributes (All Phase Types)
+
+- **repetition_id** (UUID, NOT NULL)
+  - References the experiment repetition this phase execution belongs to
+  - Links to `experiment_repetitions` table
+
+- **phase_type** (TEXT, NOT NULL, CHECK IN ('soaking', 'airdrying', 'cracking', 'shelling'))
+  - Type of phase being executed
+  - Must be one of: `soaking`, `airdrying`, `cracking`, `shelling`
+
+- **scheduled_start_time** (TIMESTAMP WITH TIME ZONE, NOT NULL)
+  - Planned start time for the phase execution
+
+- **scheduled_end_time** (TIMESTAMP WITH TIME ZONE, nullable)
+  - Planned end time for the phase execution
+  - Automatically calculated for soaking and airdrying based on duration
+
+- **actual_start_time** (TIMESTAMP WITH TIME ZONE, nullable)
+  - Actual time when the phase execution started
+
+- **actual_end_time** (TIMESTAMP WITH TIME ZONE, nullable)
+  - Actual time when the phase execution ended
+
+- **status** (TEXT, NOT NULL, DEFAULT 'pending', CHECK IN ('pending', 'scheduled', 'in_progress', 'completed', 'cancelled'))
+  - Current status of the phase execution
+
+### Phase-Specific Concepts: Independent & Dependent Variables
+
+> **Note:** This section describes the conceptual variables for each phase (what we measure or control), not necessarily the current physical columns in the database. Some of these variables will be added to the schema in future migrations.
+
+#### Soaking Phase
+
+- **Independent variables (IV)**
+  - **Pre-soaking shell moisture percentage**
+    - Moisture percentage of the shell **before soaking**.
+  - **Pre-soaking kernel moisture percentage**
+    - Moisture percentage of the kernel **before soaking**.
+  - **Average pecan diameter (inches)**
+    - Average diameter of pecans in the batch, measured in inches.
+  - **Batch weight**
+    - Total weight of the batch being soaked.
+  - **Soaking duration (minutes)**
+    - Duration of the soaking process in minutes (currently represented as `soaking_duration_minutes`).
+
+- **Dependent variables (DV)**
+  - **Post-soaking shell moisture percentage**
+    - Moisture percentage of the shell **after soaking**.
+  - **Post-soaking kernel moisture percentage**
+    - Moisture percentage of the kernel **after soaking**.
+
+#### Airdrying Phase
+
+- **Independent variables (IV)**
+  - **Airdrying duration (minutes)**
+    - Duration of the airdrying process in minutes (currently represented as `duration_minutes`).
+
+- **Dependent variables (DV)**
+  - *(TBD — moisture/other measurements after airdrying can be added here when finalized.)*
+
+#### Cracking Phase
+
+- **Independent variables (IV)**
+  - **Cracking machine type**
+    - The type of cracking machine used (linked via `machine_type_id` and `experiment_phases.cracking_machine_type_id`).
+
+- **Dependent variables (DV)**
+  - *None defined yet for cracking.*  
+    Business/analysis metrics for cracking can be added later (e.g., crack quality, breakage rates).
+
+#### Shelling Phase
+
+- **Independent variables (IV)**
+  - **Shelling machine configuration parameters** (not yet present in the DB schema)
+    - **Ring gap (inches)**
+      - Radial gap setting of the shelling ring (e.g., `0.34` inches).
+    - **Paddle RPM**
+      - Rotational speed of the paddles (integer RPM value).
+    - **Third machine parameter (TBD)**
+      - The shelling machine expects a third configuration parameter that will be defined and added to the schema later.
+
+- **Dependent variables (DV)**
+  - **Half-yield ratio (percentage)**
+    - Percentage of the shelled product that is composed of half kernels, relative to total yield.
+
+### Constraints
+
+- Combination of `repetition_id` and `phase_type` must be unique (one execution per phase type per repetition)
+
+### Notes
+
+- Phase executions are automatically created when an experiment repetition is created, based on the experiment phase template configuration
+- Sequential phases (soaking → airdrying → cracking → shelling) automatically calculate their `scheduled_start_time` based on the previous phase's `scheduled_end_time`
+- For soaking and airdrying phases, `scheduled_end_time` is automatically calculated from `scheduled_start_time` + duration
+
+---
+
+## 5. Machine Types
+
+**Table:** `machine_types`
+
+**Purpose:** Defines the types of machines available for cracking operations.
+
+### Attributes
+
+- **name** (TEXT, UNIQUE, NOT NULL)
+  - Unique name identifying the machine type
+  - Example: "JC Cracker", "Meyer Cracker"
+
+- **description** (TEXT, nullable)
+  - Optional description of the machine type
+
+### Related Tables
+
+Machine types are referenced by:
+- `experiment_phases.cracking_machine_type_id` - Defines which machine type to use for cracking in an experiment phase template
+- `experiment_phase_executions.machine_type_id` - Specifies which machine was used for a specific cracking execution
+
+---
+
+## 6. Cracker Parameters (Machine-Specific)
+
+### JC Cracker Parameters
+
+**Table:** `jc_cracker_parameters`
+
+**Purpose:** Stores parameters specific to JC Cracker machines.
+
+#### Attributes
+
+- **plate_contact_frequency_hz** (DOUBLE PRECISION, NOT NULL, CHECK > 0)
+  - Frequency of plate contact in Hertz
+
+- **throughput_rate_pecans_sec** (DOUBLE PRECISION, NOT NULL, CHECK > 0)
+  - Rate of pecan processing in pecans per second
+
+- **crush_amount_in** (DOUBLE PRECISION, NOT NULL, CHECK >= 0)
+  - Amount of crushing in inches
+
+- **entry_exit_height_diff_in** (DOUBLE PRECISION, NOT NULL)
+  - Difference in height between entry and exit points in inches
+
+### Meyer Cracker Parameters
+
+**Table:** `meyer_cracker_parameters`
+
+**Purpose:** Stores parameters specific to Meyer Cracker machines.
+
+#### Attributes
+
+- **motor_speed_hz** (DOUBLE PRECISION, NOT NULL, CHECK > 0)
+  - Motor speed in Hertz
+
+- **jig_displacement_inches** (DOUBLE PRECISION, NOT NULL)
+  - Jig displacement in inches
+
+- **spring_stiffness_nm** (DOUBLE PRECISION, NOT NULL, CHECK > 0)
+  - Spring stiffness in Newton-meters
+
+---
+
+## Summary of Entity Relationships
+
+1. **Experiment Phase** → Defines which phases are included and machine type for cracking
+2. **Experiment** → Belongs to an Experiment Phase, defines repetition requirements and weight per repetition
+3. **Experiment Repetition** → Instance of an Experiment, can be scheduled and tracked
+4. **Experiment Phase Execution** → Execution record for each phase (soaking, airdrying, cracking, shelling) within a repetition
+5. **Machine Types** → Defines available cracking machines
+6. **Cracker Parameters** → Machine-specific operational parameters (JC or Meyer)
+
+### Key Relationships
+
+- One Experiment Phase can have many Experiments
+- One Experiment can have many Experiment Repetitions
+- One Experiment Repetition can have multiple Phase Executions (one per phase type)
+- Phase Executions are automatically created based on the Experiment Phase template configuration
+- Cracking Phase Executions reference a Machine Type
+- Machine Types can have associated Cracker Parameters (JC or Meyer specific)
--- a/management-dashboard-web-app/supabase/migrations/00008_phase_data_tables.sql
+++ b/management-dashboard-web-app/supabase/migrations/00008_phase_data_tables.sql
@@ -70,6 +70,10 @@ CREATE TABLE IF NOT EXISTS public.shelling (
    scheduled_start_time TIMESTAMP WITH TIME ZONE NOT NULL,
    actual_start_time TIMESTAMP WITH TIME ZONE,
    actual_end_time TIMESTAMP WITH TIME ZONE,
+    -- The space (in inches) between the sheller's rings
+    ring_gap_inches NUMERIC(6,2) CHECK (ring_gap_inches > 0),
+    -- The revolutions per minute for the sheller drum
+    drum_rpm INTEGER CHECK (drum_rpm > 0),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    created_by UUID NOT NULL REFERENCES public.user_profiles(id),
--- a/management-dashboard-web-app/supabase/migrations/00012_unified_phase_executions.sql
+++ b/management-dashboard-web-app/supabase/migrations/00012_unified_phase_executions.sql
@@ -56,6 +56,80 @@ CREATE INDEX IF NOT EXISTS idx_phase_executions_machine_type_id
 CREATE INDEX IF NOT EXISTS idx_phase_executions_created_by 
    ON public.experiment_phase_executions(created_by);

+-- =============================================
+-- 2.5. CREATE CONDUCTOR ASSIGNMENTS TABLE
+-- =============================================
+
+-- Table to store conductor assignments to phase executions
+-- This allows multiple conductors to be assigned to each phase execution
+CREATE TABLE IF NOT EXISTS public.experiment_phase_assignments (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    phase_execution_id UUID NOT NULL REFERENCES public.experiment_phase_executions(id) ON DELETE CASCADE,
+    conductor_id UUID NOT NULL REFERENCES public.user_profiles(id) ON DELETE CASCADE,
+    
+    -- Scheduled times for this assignment (should match phase_execution times, but stored for clarity)
+    scheduled_start_time TIMESTAMP WITH TIME ZONE NOT NULL,
+    scheduled_end_time TIMESTAMP WITH TIME ZONE,
+    
+    -- Status tracking
+    status TEXT NOT NULL DEFAULT 'scheduled' 
+        CHECK (status IN ('scheduled', 'in_progress', 'completed', 'cancelled')),
+    
+    -- Optional notes about the assignment
+    notes TEXT,
+    
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    created_by UUID NOT NULL REFERENCES public.user_profiles(id),
+    
+    -- Ensure scheduled_end_time is after scheduled_start_time
+    CONSTRAINT valid_scheduled_time_range CHECK (scheduled_end_time IS NULL OR scheduled_end_time > scheduled_start_time),
+    
+    -- Ensure unique assignment per conductor per phase execution
+    CONSTRAINT unique_conductor_phase_execution UNIQUE (phase_execution_id, conductor_id)
+);
+
+-- Indexes for conductor assignments
+CREATE INDEX IF NOT EXISTS idx_phase_assignments_phase_execution_id 
+    ON public.experiment_phase_assignments(phase_execution_id);
+CREATE INDEX IF NOT EXISTS idx_phase_assignments_conductor_id 
+    ON public.experiment_phase_assignments(conductor_id);
+CREATE INDEX IF NOT EXISTS idx_phase_assignments_status 
+    ON public.experiment_phase_assignments(status);
+CREATE INDEX IF NOT EXISTS idx_phase_assignments_scheduled_start_time 
+    ON public.experiment_phase_assignments(scheduled_start_time);
+CREATE INDEX IF NOT EXISTS idx_phase_assignments_created_by 
+    ON public.experiment_phase_assignments(created_by);
+
+-- Trigger for updated_at on conductor assignments
+CREATE TRIGGER set_updated_at_phase_assignments
+    BEFORE UPDATE ON public.experiment_phase_assignments
+    FOR EACH ROW
+    EXECUTE FUNCTION public.handle_updated_at();
+
+-- Grant permissions
+GRANT ALL ON public.experiment_phase_assignments TO authenticated;
+
+-- Enable Row Level Security
+ALTER TABLE public.experiment_phase_assignments ENABLE ROW LEVEL SECURITY;
+
+-- RLS Policies for conductor assignments
+CREATE POLICY "Phase assignments are viewable by authenticated users" 
+    ON public.experiment_phase_assignments
+    FOR SELECT USING (auth.role() = 'authenticated');
+
+CREATE POLICY "Phase assignments are insertable by authenticated users" 
+    ON public.experiment_phase_assignments
+    FOR INSERT WITH CHECK (auth.role() = 'authenticated');
+
+CREATE POLICY "Phase assignments are updatable by authenticated users" 
+    ON public.experiment_phase_assignments
+    FOR UPDATE USING (auth.role() = 'authenticated');
+
+CREATE POLICY "Phase assignments are deletable by authenticated users" 
+    ON public.experiment_phase_assignments
+    FOR DELETE USING (auth.role() = 'authenticated');
+
 -- =============================================
 -- 3. FUNCTION: Calculate Sequential Phase Start Times
 -- =============================================
--- a/supabase/migrations/00008_phase_data_tables.sql
+++ b/supabase/migrations/00008_phase_data_tables.sql
@@ -70,6 +70,10 @@ CREATE TABLE IF NOT EXISTS public.shelling (
    scheduled_start_time TIMESTAMP WITH TIME ZONE NOT NULL,
    actual_start_time TIMESTAMP WITH TIME ZONE,
    actual_end_time TIMESTAMP WITH TIME ZONE,
+    -- The space (in inches) between the sheller's rings
+    ring_gap_inches NUMERIC(6,2) CHECK (ring_gap_inches > 0),
+    -- The revolutions per minute for the sheller drum
+    drum_rpm INTEGER CHECK (drum_rpm > 0),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    created_by UUID NOT NULL REFERENCES public.user_profiles(id),
--- a/supabase/migrations/00012_unified_phase_executions.sql
+++ b/supabase/migrations/00012_unified_phase_executions.sql
@@ -56,6 +56,80 @@ CREATE INDEX IF NOT EXISTS idx_phase_executions_machine_type_id
 CREATE INDEX IF NOT EXISTS idx_phase_executions_created_by 
    ON public.experiment_phase_executions(created_by);

+-- =============================================
+-- 2.5. CREATE CONDUCTOR ASSIGNMENTS TABLE
+-- =============================================
+
+-- Table to store conductor assignments to phase executions
+-- This allows multiple conductors to be assigned to each phase execution
+CREATE TABLE IF NOT EXISTS public.experiment_phase_assignments (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    phase_execution_id UUID NOT NULL REFERENCES public.experiment_phase_executions(id) ON DELETE CASCADE,
+    conductor_id UUID NOT NULL REFERENCES public.user_profiles(id) ON DELETE CASCADE,
+    
+    -- Scheduled times for this assignment (should match phase_execution times, but stored for clarity)
+    scheduled_start_time TIMESTAMP WITH TIME ZONE NOT NULL,
+    scheduled_end_time TIMESTAMP WITH TIME ZONE,
+    
+    -- Status tracking
+    status TEXT NOT NULL DEFAULT 'scheduled' 
+        CHECK (status IN ('scheduled', 'in_progress', 'completed', 'cancelled')),
+    
+    -- Optional notes about the assignment
+    notes TEXT,
+    
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    created_by UUID NOT NULL REFERENCES public.user_profiles(id),
+    
+    -- Ensure scheduled_end_time is after scheduled_start_time
+    CONSTRAINT valid_scheduled_time_range CHECK (scheduled_end_time IS NULL OR scheduled_end_time > scheduled_start_time),
+    
+    -- Ensure unique assignment per conductor per phase execution
+    CONSTRAINT unique_conductor_phase_execution UNIQUE (phase_execution_id, conductor_id)
+);
+
+-- Indexes for conductor assignments
+CREATE INDEX IF NOT EXISTS idx_phase_assignments_phase_execution_id 
+    ON public.experiment_phase_assignments(phase_execution_id);
+CREATE INDEX IF NOT EXISTS idx_phase_assignments_conductor_id 
+    ON public.experiment_phase_assignments(conductor_id);
+CREATE INDEX IF NOT EXISTS idx_phase_assignments_status 
+    ON public.experiment_phase_assignments(status);
+CREATE INDEX IF NOT EXISTS idx_phase_assignments_scheduled_start_time 
+    ON public.experiment_phase_assignments(scheduled_start_time);
+CREATE INDEX IF NOT EXISTS idx_phase_assignments_created_by 
+    ON public.experiment_phase_assignments(created_by);
+
+-- Trigger for updated_at on conductor assignments
+CREATE TRIGGER set_updated_at_phase_assignments
+    BEFORE UPDATE ON public.experiment_phase_assignments
+    FOR EACH ROW
+    EXECUTE FUNCTION public.handle_updated_at();
+
+-- Grant permissions
+GRANT ALL ON public.experiment_phase_assignments TO authenticated;
+
+-- Enable Row Level Security
+ALTER TABLE public.experiment_phase_assignments ENABLE ROW LEVEL SECURITY;
+
+-- RLS Policies for conductor assignments
+CREATE POLICY "Phase assignments are viewable by authenticated users" 
+    ON public.experiment_phase_assignments
+    FOR SELECT USING (auth.role() = 'authenticated');
+
+CREATE POLICY "Phase assignments are insertable by authenticated users" 
+    ON public.experiment_phase_assignments
+    FOR INSERT WITH CHECK (auth.role() = 'authenticated');
+
+CREATE POLICY "Phase assignments are updatable by authenticated users" 
+    ON public.experiment_phase_assignments
+    FOR UPDATE USING (auth.role() = 'authenticated');
+
+CREATE POLICY "Phase assignments are deletable by authenticated users" 
+    ON public.experiment_phase_assignments
+    FOR DELETE USING (auth.role() = 'authenticated');
+
 -- =============================================
 -- 3. FUNCTION: Calculate Sequential Phase Start Times
 -- =============================================