usda-vision/docs/database_entities.md

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)