# 3D Facility Viewer Enhancement Plan

## Overview

Two major enhancements to transform the 3D facility viewer into a comprehensive, investor-ready data visualization platform.

---

## Part 1: Visual Style Refactor

### Goal

Replace 3D spheres with informative 2D icons/shapes that convey plant stage and health at a glance, while adding grid overlays for human readability.

### Current State

- Plants are 3D spheres with color coding
- No visible grid structure
- Stage indicated only by color

### Target State

- Flat 2D icons/polygons per growth stage
- Visible row/column/tier grid lines
- Labels for navigation (R1, R2, C1, C2, T1, T2)
- Information-dense schematic view

### Technical Approach

#### Phase 1.1: Plant Icon System

Replace sphereGeometry with stage-specific 2D shapes:

| Stage | Shape | Color | Icon Concept |
|-------|-------|-------|--------------|
| CLONE_IN | Small circle | #3b82f6 Blue | Seedling dot |
| VEGETATIVE | Leaf polygon | #22c55e Green | 3-point leaf |
| FLOWERING | Flower polygon | #a855f7 Purple | 5-petal flower |
| DRYING | Diamond | #f97316 Orange | Hanging diamond |
| CURING | Square | #92400e Brown | Jar square |
| HARVESTED | Circle outline | #6b7280 Gray | Empty circle |

Implementation:

- Use @react-three/drei Billboard for camera-facing icons
- Create SVG paths for each stage
- Scale based on zoom level
- Add pulse animation for highlighted plants

#### Phase 1.2: Grid Visualization

Add visible structure lines:

- Horizontal lines for rows (labeled R1-R8)
- Vertical lines for columns (labeled C1-C10)  
- Tier indicators (T1-T3 vertical markers)
- Semi-transparent to not obscure content
- Toggle on/off via UI

#### Phase 1.3: Section Improvements

- Section boundaries with labeled borders
- Section name prominently displayed
- Row/column count indicator
- Plant count badge

### Files to Modify

- PlantSystem.tsx - Replace sphere with icon system
- SmartRack.tsx - Add grid overlay
- types.ts - Add icon type definitions
- New: PlantIcon.tsx, GridOverlay.tsx, SectionLabel.tsx

---

## Part 2: Plant Data Visualization System

### Goal

Create a comprehensive data card with lifecycle timeline, sensor data, and hierarchical drill-down capabilities.

### Components

#### 2.1: PlantDataCard (Main Component)

A glassmorphic panel with:

1. Header - Entity name, METRC tag, quick status badges
2. Timeline - Visual lifecycle from clone to cure
3. Vitals Grid - Health, temp, VPD, humidity gauges
4. Activity Feed - Recent events/actions
5. Actions - Quick action buttons

#### 2.2: Lifecycle Timeline Component

SVG-animated timeline showing plant journey:

- Horizontal timeline with stage nodes
- Filled nodes for completed stages
- Animated current stage indicator
- Day count labels
- Estimated completion
- Click stages to see historical data

SVG Animation Ideas:

- Pulse effect on current stage
- Growth animation between stages
- Color gradient transitions
- Hover: expand stage details

#### 2.3: VitalGauge Component

Radial or bar gauge for sensor readings:

- Animated fill based on value
- Color coding: Green (optimal), Yellow (warning), Red (critical)
- Sparkline showing 24h/7d trend
- Threshold markers
- Animated value counter

#### 2.4: Drill-Down Aggregation

Levels:

| Level | Data Shown | Aggregation |
|-------|-----------|-------------|
| Plant | Individual readings | Raw values |
| Tier | All plants on tier | Avg/Min/Max |
| Section | All tiers in section | Avg/Min/Max |
| Room | All sections in room | Avg/Range |
| Floor | All rooms | Summary counts |

Implementation:

- useAggregatedData(level, entityId) hook
- Calculates averages, ranges, outliers
- Returns unified data shape for PlantDataCard

#### 2.5: Mock Data Generator

Rich, realistic demo data including:

- Stage history with dates
- Vitals: health, temperature, humidity, VPD with history
- Touch points, photos, notes, alerts
- Position data

Data Generation:

- Realistic stage duration distributions
- Seasonal temperature variations
- Circadian VPD patterns
- Random but plausible health events
- IPM schedule adherence
- Growth curve progression

---

## Part 3: Implementation Phases

### Sprint 1: Icon System & Grid (2-3 days)

1. Create PlantIcon component with stage shapes
2. Implement GridOverlay with row/column lines
3. Add section labels with plant counts
4. Toggle for grid visibility
5. Test rendering performance

### Sprint 2: Data Card Foundation (2-3 days)

1. Create PlantDataCard shell component
2. Implement glassmorphic styling
3. Add header with entity info
4. Wire up to plant selection
5. Position card in UI (side panel or overlay)

### Sprint 3: Lifecycle Timeline (1-2 days)

1. Create LifecycleTimeline component
2. SVG path animations
3. Stage click handlers
4. Day calculation logic
5. Integration with data card

### Sprint 4: Vital Gauges (1-2 days)

1. Create VitalGauge component
2. Animated value display
3. Color thresholds
4. Sparkline mini-charts
5. Mock sensor data hookup

### Sprint 5: Aggregation & Drill-down (2 days)

1. Implement useAggregatedData hook
2. Level switcher UI
3. Data roll-up calculations
4. Update card content per level
5. Breadcrumb navigation integration

### Sprint 6: Mock Data & Polish (1-2 days)

1. Build comprehensive mock data generator
2. Performance optimization
3. Animation polish
4. Mobile responsive adjustments
5. Accessibility review

---

## File Structure

frontend/src/components/facility3d/

- coordinates.ts (existing)
- PlantSystem.tsx (refactor to use icons)
- PlantIcon.tsx (NEW - stage icons)
- GridOverlay.tsx (NEW - grid lines)
- SectionLabel.tsx (NEW - section info)
- PlantDataCard/
  - index.tsx
  - LifecycleTimeline.tsx
  - VitalGauge.tsx
  - ActivityFeed.tsx
  - ActionButtons.tsx
- hooks/
  - useAggregatedData.ts
  - usePlantLifecycle.ts
- mocks/
  - plantDataGenerator.ts

---

## Success Criteria

1. Visual Clarity - Investors understand facility layout in <5 seconds
2. Stage Recognition - Growth stages identifiable without color dependency
3. Data Richness - All relevant plant data visible in single card
4. Performance - 60fps with 500+ plants rendered
5. Interactivity - Smooth animations, responsive drill-down
6. Realism - Mock data feels like real cultivation facility

---

## Open Questions

1. Should the data card be a side panel (persistent) or overlay (modal)?
2. Preferred icon style: geometric shapes, emoji, or custom SVG illustrations?
3. Priority between "pretty" vs "informative" if tradeoffs arise?
4. Any specific Metrc fields that MUST be displayed?