usda-vision/docs/DESIGN_RECOMMENDATION_SUMMARY.md

Database Design Recommendation Summary

Critical Issue Identified

Your current design has a fundamental flaw that prevents it from working correctly with repetitions:

The Problem

The phase tables (soaking, airdrying, cracking, shelling) have this constraint:

CONSTRAINT unique_soaking_per_experiment UNIQUE (experiment_id)

This means you can only have ONE soaking record per experiment, even if you have 3 repetitions! This breaks your entire repetition system.

Why This Happens

When you create an experiment with 3 repetitions:

1. ✅ 3 rows are created in experiment_repetitions
2. ❌ But you can only create 1 row in soaking (due to UNIQUE constraint)
3. ❌ The other 2 repetitions cannot have soaking data!

Design Assessment

Current Approach: Separate Tables (❌ Not Recommended)

Problems:

• ❌ UNIQUE constraint breaks repetitions
• ❌ Schema duplication (same structure 4 times)
• ❌ Hard to query "all phases for a repetition"
• ❌ Sequential timing calculations are complex and error-prone
• ❌ No automatic phase creation when repetitions are created

Recommended Approach: Unified Table (✅ Best Practice)

Benefits:

• ✅ Properly supports repetitions (one phase per repetition)
• ✅ Automatic phase creation via database trigger
• ✅ Simple sequential time calculations
• ✅ Easy to query all phases for a repetition
• ✅ Single source of truth
• ✅ Easier to maintain and extend

Recommended Solution

I've created a migration file that implements a unified experiment_phase_executions table:

Key Features:

1. Single Table for All Phases

   • Uses phase_type enum to distinguish phases
   • One row per phase per repetition
   • Proper UNIQUE constraint: (repetition_id, phase_type)

2. Automatic Phase Creation

   • Database trigger automatically creates phase executions when a repetition is created
   • Based on the experiment's phase configuration (has_soaking, has_airdrying, etc.)

3. Automatic Sequential Timing

   • Database trigger calculates sequential start times
   • If soaking ends at 5pm, airdrying automatically starts at 5pm
   • If airdrying ends at 5:12pm, cracking automatically starts at 5:12pm

4. Backward Compatibility Views

   • Views created for soaking_view, airdrying_view, etc.
   • Existing code can continue to work (with minor updates)

Files Created

1. docs/database_design_analysis.md - Detailed analysis with comparison matrix
2. management-dashboard-web-app/supabase/migrations/00012_unified_phase_executions.sql - Complete migration implementation

Migration Path

1. Review the analysis document
2. Test the migration on a development database
3. Update application code to use the new table structure
4. Migrate existing data (if any)
5. Drop old phase tables after verification

Alternative: Fix Current Design

If you prefer to keep separate tables, you MUST:

1. Remove UNIQUE (experiment_id) constraints from all phase tables
2. Keep only UNIQUE (repetition_id) constraints
3. Add trigger to auto-create phase entries when repetitions are created
4. Fix sequential timing calculations to use repetition_id instead of experiment_id

However, this still has the drawbacks of schema duplication and complexity.

Recommendation

Use the unified table approach - it's cleaner, more maintainable, and properly supports your repetition model.