MODEL/usda-vision
10
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'old-github/main' into integrate-old-refactors-of-github

Browse Source
This commit is contained in:
Alireza Vaezi
2026-03-09 13:10:08 -04:00
parent 78bfcf0261 9e97893c89
commit cd55dda295
35 changed files with 2878 additions and 688 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
docs/DESIGN_RECOMMENDATION_SUMMARY.md
View File

@@ -7,6 +7,7 @@ Your current design has a **fundamental flaw** that prevents it from working cor
### The Problem
The phase tables (`soaking`, `airdrying`, `cracking`, `shelling`) have this constraint:
```sql
CONSTRAINT unique_soaking_per_experiment UNIQUE (experiment_id)
```
@@ -16,7 +17,8 @@ This means you can **only have ONE soaking record per experiment**, even if you
### Why This Happens
When you create an experiment with 3 repetitions:
1. ✅ 3 rows are created in `experiment_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!
@@ -25,6 +27,7 @@ When you create an experiment with 3 repetitions:
### 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"
@@ -34,6 +37,7 @@ When you create an experiment with 3 repetitions:
### Recommended Approach: Unified Table (✅ Best Practice)
**Benefits:**
- ✅ Properly supports repetitions (one phase per repetition)
- ✅ Automatic phase creation via database trigger
- ✅ Simple sequential time calculations
@@ -45,7 +49,7 @@ When you create an experiment with 3 repetitions:
I've created a migration file that implements a **unified `experiment_phase_executions` table**:
### Key Features:
### Key Features
1. **Single Table for All Phases**
- Uses `phase_type` enum to distinguish phases
@@ -68,7 +72,8 @@ I've created a migration file that implements a **unified `experiment_phase_exec
## 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
3. **`supabase/migrations/00012_unified_phase_executions.sql`** - Complete migration implementation
## Migration Path
@@ -81,6 +86,7 @@ I've created a migration file that implements a **unified `experiment_phase_exec
## 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
@@ -91,4 +97,3 @@ 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.

18
docs/SUPABASE_DOCKER_COMPOSE.md
View File

@@ -5,6 +5,7 @@ The Supabase containers are now integrated into the main `docker-compose.yml` fi
## What Changed
All Supabase services are now defined in the root `docker-compose.yml`:
- **supabase-db**: PostgreSQL database (port 54322)
- **supabase-rest**: PostgREST API (port 54321)
- **supabase-auth**: GoTrue authentication service (port 9999)
@@ -48,27 +49,34 @@ VITE_SUPABASE_ANON_KEY=<your-anon-key>
```
The default anon key for local development is:
```
<<<<<<< HEAD
[REDACTED]
=======
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24iLCJleHAiOjE5ODM4MTI5OTZ9.CRXP1A7WOeoJeXxjNni43kdQwgnWNReilDMblYTn_I0
>>>>>>> old-github/main
```
### Migrations
Migrations are automatically run on first startup via the `supabase-migrate` service. The service:
1. Waits for the database to be ready
2. Runs all migrations from `supabase/migrations/` in alphabetical order
3. Runs seed files (`seed_01_users.sql` and `seed_02_phase2_experiments.sql`)
If you need to re-run migrations, you can:
1. Stop the containers: `docker compose down`
2. Remove the database volume: `docker volume rm usda-vision_supabase-db`
3. Start again: `docker compose up -d`
### Accessing Services
- **Supabase API**: http://localhost:54321
- **Supabase Studio**: http://localhost:54323
- **Email Testing (Inbucket)**: http://localhost:54324
- **Supabase API**: <http://localhost:54321>
- **Supabase Studio**: <http://localhost:54323>
- **Email Testing (Inbucket)**: <http://localhost:54324>
- **Database (direct)**: localhost:54322
### Network
@@ -88,12 +96,14 @@ If you were previously using `supabase start` from the `management-dashboard-web
### Port Conflicts
If you get port conflicts, make sure:
- No other Supabase instances are running
- The Supabase CLI isn't running containers (`supabase stop` if needed)
### Migration Issues
If migrations fail:
1. Check the logs: `docker compose logs supabase-migrate`
2. Ensure migration files are valid SQL
3. You may need to manually connect to the database and fix issues
@@ -101,7 +111,7 @@ If migrations fail:
### Database Connection Issues
If services can't connect to the database:
1. Check database is healthy: `docker compose ps supabase-db`
2. Check logs: `docker compose logs supabase-db`
3. Ensure the database password matches across all services

25
docs/SUPABASE_MIGRATION.md
View File

@@ -25,6 +25,7 @@ docker compose up -d
### For Supabase CLI Users
**Before** (old way):
```bash
cd management-dashboard-web-app
supabase start
@@ -32,6 +33,7 @@ supabase db reset
```
**After** (new way):
```bash
# From project root - no need to cd!
supabase start
@@ -50,23 +52,22 @@ If you have scripts or documentation that reference the old path, update them:
- ❌ `management-dashboard-web-app/supabase/config.toml`
- ✅ `supabase/config.toml`
## Backward Compatibility
The old directory (`management-dashboard-web-app/supabase/`) can be kept for reference, but it's no longer used by docker-compose or the Supabase CLI. You can safely remove it after verifying everything works:
## Current State
```bash
# After verifying everything works with the new location
rm -rf management-dashboard-web-app/supabase
```
The old directory (`management-dashboard-web-app/supabase/`) has been removed. All Supabase and DB configuration, migrations, and seeds now live only under the project root `supabase/` directory. Docker Compose and the Supabase CLI use root `supabase/` exclusively.
## Verification
To verify the migration worked:
To verify the migration:
1. **Check docker-compose paths** (only root supabase should be referenced):
1. **Check docker-compose paths**:
```bash
grep -r "supabase" docker-compose.yml
# Should show: ./supabase/ (not ./management-dashboard-web-app/supabase/)
grep "supabase" docker-compose.yml
# Should show only ./supabase/ (no management-dashboard-web-app/supabase/)
```
2. **Test Supabase CLI**:
@@ -76,7 +77,8 @@ To verify the migration worked:
# Should work without needing to cd into management-dashboard-web-app
```
3. **Test migrations**:
1. **Test migrations**:
```bash
docker compose up -d
docker compose logs supabase-migrate
@@ -90,4 +92,3 @@ To verify the migration worked:
✅ Easier to share database across services
✅ Better alignment with monorepo best practices
✅ Infrastructure separated from application code

303
docs/database_entities.md Normal file
View File

@@ -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)