# 3D Facility Viewer Refactor Plan: "Project Panopticon"

## 1. Executive Summary

**Objective:** Transform the 3D Facility Viewer from a basic visualization tool into a comprehensive, "dead simple" interface for managing complex facility operations.
**Core Philosophy:** "Functional Realism". The interface should look premium and architectural, but every visual element must serve a data-driven purpose.
**Key Goals:**

1. **Human Readability:** Instant understanding of facility layout, plant locations, and environmental status.
2. **Temporal Visualization:** Ability to visualize data *over time* (e.g., "Show me the spread of this batch over the last 30 days").
3. **Rapid Location:** Locate any METRC-compliant plant or batch instantly with clear visual guidance.

## 2. Visual & UX Overhaul

### A. "Clean Industrial" Aesthetics

* **Move away from:** Wireframes, glowing neon lines, dark "hacker" themes.
* **Move toward:** Clean concrete textures, matte metal finishes, soft global illumination, and distinct color coding for biological vs. structural elements.
* **Lighting:** Use an HDRI environment (`preset="city"` or similar) for realistic reflections, plus soft ambient occlusion (`<ContactShadows />`) to ground objects.

### B. "Human Readable" Indicators

* **Smart Labels:** Instead of static 3D text floating in space, use `Html` overlays that scale and fade based on camera distance (LOD).
  * *Close Zoom:* Show individual Plant Tags and Health Stats.
  * *Medium Zoom:* Show Rack/Shelf IDs and Aggregate Health.
  * *Far Zoom:* Show Room Names and Environmental Averages.
* **Beacons:** When searching for a plant, do not just snap the camera. Place a vertical "light beacon" or animated indicator over the target so the user sees *where* it is in context before zooming in.

### C. Controls & Navigation

* **Hybrid Controls:**
  * **WASD + Right Click Drag:** For "gamer" style free-flight.
  * **Click-to-Move:** Click any room floor to smoothly fly the camera there.
  * **Double-Click:** Focus specifically on a rack or plant.
* **Tour Mode:** A "Next Issue" button to cycle the camera through all plants with "Critical" health or environmental alerts.

## 3. New Feature: "The Time Slider"

* **Concept:** A timeline interface at the bottom of the screen.
* **Function:** Dragging the slider behaves like a video scrubber.
  * *Past:* Visualize historical plant positions (from `PlantLocationHistory`). See where a batch started and how it moved.
  * *Present:* Live state.
  * *Future (Projected):* Visualize yield forecasts or space planning (from `Yield` model).

## 4. Technical Architecture Refactor

### A. Component Decomposition

The current `Facility3DViewerPage.tsx` is becoming monolithic. We will break it down:

* `FacilityScene.tsx`: Main canvas and lighting setup.
* `FacilityWorld.tsx`: Handles the "physics" and separate rooms.
* `RoomObject.tsx`: Encapsulates a single room's logic (floor, walls, labels).
* `SmartRack.tsx`: Manages a single rack/section, including its tiers and labels.
* `PlantSystem.tsx`: Optimized `InstancedMesh` system for rendering thousands of plants efficiently.

### B. Data & State Management

* **Zustand Store:** Move 3D state (selected plant, camera target, visualization mode, timeline position) out of React `useState` and into a global store for better performance and access outside the canvas.
* **React Query:** Use for fetching standard API data.
* **Optimized History Fetching:** New API endpoint needed: `GET /api/facilities/:id/history-snapshot?date=ISO_DATE` to fetch the state of the facility at a specific point in time.

## 5. Implementation Phases

### Phase 1: The "Visual Foundation" (Current Priority)

* [x] Split code into smaller components.
* [x] Implement "Clean Industrial" materials and lighting. *(Using Environment preset="city", ContactShadows)*
* [x] Fix the camera controller to be "smooth yet precise". *(CameraControls with WASD + mouse)*
* [ ] Add "LOD" (Level of Detail) labels that fade in/out. *(Future enhancement)*

### Phase 2: "Search & Locate" (Locating Plants) ✅ COMPLETE

* [x] Build the "Search Sidebar" with fuzzy search for Tags/Batches. *(PlantSearch.tsx)*
* [x] Implement the "Beacon" visual indicator system. *(Beacon.tsx - animated light beam)*
* [x] Add "Highlight Mode": Dim the entire facility *except* the search results. *(dimMode + highlightedTags)*

### Phase 3: "The Time Machine"

* [ ] Implement the UI Slider component.
* [ ] Create backend endpoint for historical snapshots.
* [ ] Wire up the slider to update plant positions dynamically.

## 6. Review Request

Does this plan align with your vision for "dead simple" and "human readable"? specifically:

1. Is the **Time Slider** a desired feature for "complex data over time"?
2. Do you agree with the **"Clean Industrial"** aesthetic direction?