01 - CAD Integration Overview

Architecture and concept explanation for the Water Treatment Plant CAD integration

---

Purpose

The CAD integration feature enables users to:

1. Visualize a 3D water treatment plant model
2. Select individual components (tanks, filters, pipes, etc.)
3. Extract water quality metadata from selected components
4. Run ML predictions using the extracted parameters
5. View results and recommendations

---

System Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                           CAD INTEGRATION SYSTEM                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                         PRESENTATION LAYER                           │   │
│  │                                                                       │   │
│  │   ┌───────────────┐  ┌───────────────┐  ┌───────────────────────┐   │   │
│  │   │  3D Viewport  │  │  Input Form   │  │   Results Panel       │   │   │
│  │   │               │  │               │  │                       │   │   │
│  │   │ - WTP Model   │  │ - Parameters  │  │ - Predictions         │   │   │
│  │   │ - Selection   │  │ - Fetch Btn   │  │ - Recommendations     │   │   │
│  │   │ - Tooltips    │  │ - Run Models  │  │ - Risk Assessment     │   │   │
│  │   └───────────────┘  └───────────────┘  └───────────────────────┘   │   │
│  │                                                                       │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                      │                                       │
│                                      ▼                                       │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                          STATE LAYER                                 │   │
│  │                                                                       │   │
│  │   ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐     │   │
│  │   │ selectedComponent│  │ inputParameters │  │ modelResults    │     │   │
│  │   │ (string | null) │  │ (TreatmentInput)│  │ (Results)       │     │   │
│  │   └─────────────────┘  └─────────────────┘  └─────────────────┘     │   │
│  │                                                                       │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                      │                                       │
│                                      ▼                                       │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                         DATA LAYER                                   │   │
│  │                                                                       │   │
│  │   ┌─────────────────────────────────────────────────────────────┐   │   │
│  │   │                  COMPONENT METADATA STORE                    │   │   │
│  │   │                                                               │   │   │
│  │   │   componentId → {                                             │   │   │
│  │   │     name: string,                                             │   │   │
│  │   │     type: ComponentType,                                      │   │   │
│  │   │     metadata: TreatmentInput | WastewaterInput,               │   │   │
│  │   │     position: Vector3,                                        │   │   │
│  │   │     description: string                                       │   │   │
│  │   │   }                                                           │   │   │
│  │   │                                                               │   │   │
│  │   └─────────────────────────────────────────────────────────────┘   │   │
│  │                                                                       │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                      │                                       │
│                                      ▼                                       │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                         ML API LAYER                                 │   │
│  │                                                                       │   │
│  │   ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐     │   │
│  │   │ useReusability  │  │ useTreatment    │  │ useTwinEngine   │     │   │
│  │   │ Prediction()    │  │ Recommendation()│  │ (Combined)      │     │   │
│  │   └─────────────────┘  └─────────────────┘  └─────────────────┘     │   │
│  │                                                                       │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

---

Data Flow

Step 1: Component Selection

User clicks on 3D component
         │
         ▼
┌─────────────────────────────────┐
│ onComponentSelect(componentId)  │
│                                 │
│ - Highlight component           │
│ - Show tooltip with info        │
│ - Update selectedComponent      │
└─────────────────────────────────┘

Step 2: Fetch Parameters

User clicks "Fetch Parameters" button
         │
         ▼
┌─────────────────────────────────┐
│ fetchComponentMetadata()        │
│                                 │
│ - Get metadata from store       │
│ - Map to input parameters       │
│ - Populate form fields          │
└─────────────────────────────────┘

Step 3: Run Model

User selects model and clicks "Run"
         │
         ▼
┌─────────────────────────────────┐
│ runSelectedModel()              │
│                                 │
│ - Validate input parameters     │
│ - Call ML API endpoint          │
│ - Display results               │
└─────────────────────────────────┘

---

Component Types

type WTPComponentType =
  | "inlet" // Raw water intake
  | "screening" // Coarse screening
  | "grit_chamber" // Grit removal
  | "primary_clarifier" // Primary settling
  | "aeration_tank" // Biological treatment
  | "secondary_clarifier" // Secondary settling
  | "filtration" // Sand/media filtration
  | "disinfection" // Chlorination/UV
  | "outlet" // Treated water outlet
  | "sludge_thickener" // Sludge handling
  | "sludge_digester" // Anaerobic digestion
  | "dewatering"; // Sludge dewatering

---

Model Selection (3 Models Only)

The CAD integration page will feature three models (excluding Adaptive Optimizer):

1. Prediction Model (Reusability)

• Purpose: Classify water reusability potential
• Input: WastewaterInput parameters
• Output: Reusability class (drinking, irrigation, industrial, etc.)
• Hook: useReusabilityPrediction()

2. Treatment Model

• Purpose: Recommend treatment stage and steps
• Input: TreatmentInput parameters
• Output: Treatment stage, steps, chemical suggestions
• Hook: useTreatmentRecommendation()

3. Twin Engine Model

• Purpose: Combined analysis using both models
• Input: Both WastewaterInput and TreatmentInput
• Output: Comprehensive analysis with both predictions
• Hook: Uses both hooks sequentially

---

State Management

interface CADIntegrationState {
  // 3D Model State
  selectedComponent: string | null;
  hoveredComponent: string | null;
  cameraPosition: [number, number, number];

  // Input Parameters
  inputMode: "treatment" | "reusability" | "combined";
  treatmentInput: TreatmentInput;
  reusabilityInput: WastewaterInput;

  // Model Selection
  selectedModel: "prediction" | "treatment" | "twin-engine";

  // Results
  predictionResult: ReusabilityResult | null;
  treatmentResult: TreatmentResult | null;

  // UI State
  isLoading: boolean;
  error: string | null;
  showResults: boolean;
}

---

Key Interactions

1. Component Click

const handleComponentClick = (componentId: string) => {
  setSelectedComponent(componentId);

  // Get component info
  const component = componentStore[componentId];

  // Show info panel
  setComponentInfo({
    name: component.name,
    type: component.type,
    description: component.description,
    hasMetadata: !!component.metadata,
  });
};

2. Fetch Parameters

const handleFetchParameters = () => {
  if (!selectedComponent) return;

  const component = componentStore[selectedComponent];
  const metadata = component.metadata;

  // Map metadata to appropriate input type
  if (selectedModel === "treatment" || selectedModel === "twin-engine") {
    setTreatmentInput(mapToTreatmentInput(metadata));
  }

  if (selectedModel === "prediction" || selectedModel === "twin-engine") {
    setReusabilityInput(mapToReusabilityInput(metadata));
  }
};

3. Run Model

const handleRunModel = async () => {
  setIsLoading(true);

  try {
    switch (selectedModel) {
      case "prediction":
        const reusability = await predictReusability(reusabilityInput);
        setPredictionResult(reusability);
        break;

      case "treatment":
        const treatment = await recommendTreatment(treatmentInput);
        setTreatmentResult(treatment);
        break;

      case "twin-engine":
        const [reusabilityRes, treatmentRes] = await Promise.all([predictReusability(reusabilityInput), recommendTreatment(treatmentInput)]);
        setPredictionResult(reusabilityRes);
        setTreatmentResult(treatmentRes);
        break;
    }

    setShowResults(true);
  } catch (error) {
    setError(error.message);
  } finally {
    setIsLoading(false);
  }
};

---

File Structure

src/
├── app/(core)/cad-integration/
│   ├── page.tsx                    # Main CAD integration page
│   ├── components/
│   │   ├── WTPModel3D.tsx          # 3D water treatment plant
│   │   ├── ComponentSelector.tsx   # Component selection UI
│   │   ├── ParameterForm.tsx       # Input parameter form
│   │   ├── ModelSelector.tsx       # Model selection tabs
│   │   ├── ResultsPanel.tsx        # Results display
│   │   └── ComponentTooltip.tsx    # Hover tooltip
│   ├── hooks/
│   │   ├── useCADState.ts          # State management
│   │   └── useComponentMetadata.ts # Metadata handling
│   └── data/
│       ├── components.ts           # Component definitions
│       └── metadata-templates.ts   # Default metadata values
└── lib/cad-integration/
    ├── types.ts                    # Type definitions
    ├── metadata-mapper.ts          # Metadata to input mapping
    └── component-store.ts          # Component data store

---

Integration Points

Existing Hooks (Reuse)

• useReusabilityPrediction() from @/lib/ml-api/hooks
• useTreatmentRecommendation() from @/lib/ml-api/hooks

Existing Types (Reuse)

• TreatmentInput from @/lib/ml-api/types
• WastewaterInput from @/lib/ml-api/types
• TreatmentResult from @/lib/ml-api/types
• ReusabilityResult from @/lib/ml-api/types

New Components (Create)

• 3D WTP Model with selectable components
• Component metadata store
• Parameter fetch mechanism
• Model selection UI

---

Next: 02-COMPONENT-METADATA.md

Learn how CAD components map to input parameters →