# Grow Room Heatmap - Feature Spec

**Priority**: 🟡 High (Phase 2)  
**Team**: 777 Wolfpack  
**Date**: 2025-12-09  
**Status**: Ready for Implementation

---

## 📋 Overview

Visual heat-map representation of plant health across a multi-level grow room. Reduces cognitive load by showing problems as color-coded zones instead of text lists.

**Key Benefit**: Growers can instantly see which beds need attention at a glance.

---

## 🏗️ Room Model

### Structure

- **2 Levels**: `floor_1` (ground), `floor_2` (scaffolding)
- **Fixed Grid**: Same rows/columns on each floor
- **Beds**: Individual growing beds in grid positions

### Bed Data Model

```typescript
interface Bed {
  bed_id: string;
  floor: 'floor_1' | 'floor_2';
  row: number;
  column: number;
  plant_batch_id?: string;
  status: 'active' | 'empty' | 'maintenance';
  health_score: number; // 0-100
  sensors?: {
    temp?: number;
    humidity?: number;
    ec?: number;
    par?: number;
  };
  last_alert?: string;
}
```

---

## 🎨 UX Design

### Main Canvas

- Grid visualization of room layout
- Floor toggle (Floor 1 / Floor 2)
- Color-coded heat map cells
- Hover tooltips with bed details
- Legend showing health score ranges

### Color Scale

- **90-100**: Dark green (excellent)
- **70-89**: Light green (good)
- **50-69**: Yellow (fair)
- **30-49**: Orange (needs attention)
- **0-29**: Red (critical)
- **Empty**: Gray outline (no plant)

### Interactions

- **Hover**: Show tooltip with bed info
- **Click**: Navigate to bed detail page
- **Toggle**: Switch between floors
- **Legend**: Show color scale reference

---

## 🔧 Implementation Plan

### Components

1. `GrowRoomHeatmap.tsx` - Main container
2. `FloorGrid.tsx` - Grid visualization
3. `BedCell.tsx` - Individual bed cell
4. `BedTooltip.tsx` - Hover tooltip
5. `FloorToggle.tsx` - Floor selector
6. `HealthLegend.tsx` - Color scale legend

### API Endpoints

- `GET /api/rooms/:roomId/layout` - Room structure
- `GET /api/rooms/:roomId/health` - Current health data

---

## 📊 Success Metrics

- Growers can identify problem areas in < 5 seconds
- Reduce time spent reviewing text lists by 80%
- Increase early problem detection by 50%

---

**Status**: ✅ Spec Complete - Ready for Implementation
