UI-Prototype/CLAUDE.md

CLAUDE.md — frontend

Angular 21 SPA. Multi-tenant dashboard with a lazy-loaded src.palm.vision sub-app for MPOB-standard palm oil fruit bunch (FFB) ripeness detection. Three inference engines: browser ONNX WASM, browser TFLite WASM, and NestJS remote (WebSocket).

Commands

npm start                   # Dev server at 0.0.0.0:4200
npm run build               # Production build → dist/fisapp-ui
npm run build:dev           # Dev build → dist/dev
npm run build:prod          # Prod build → dist/rc
npm run build:leave:prod    # Leave-module variant
npm run build:quot:prod     # Quotation variant
npm run build:maf:quot:prod # MAF quotation variant
npm run test                # Karma + Jasmine
npm run clean               # Clear Angular + npm caches

Architecture

Application Shell (src/app/)

• app.config.ts — ApplicationConfig: bootstraps NGXS root store (withNgxsStoragePlugin({keys:'*'}), withNgxsReduxDevtoolsPlugin), Angular Router (hash location, onSameUrlNavigation:'reload'), HTTP client, service worker (registered immediately).
• app.routes.ts — Root routes: dashboard, auth, leave, tender, src.palm.vision (all lazy-loaded except dashboard).
• app.component.ts — Root component: 30-minute session timeout, PWA install prompt, theme management (light/dark + blue/pink), multi-language (en_US, ms_MY, zh_Hans), maintenance mode alert.

PalmVision Sub-App (src/src.palm.vision/)

Lazy-loaded at /src.palm.vision. Provides its own NGXS VisionState via provideStates([VisionState]) in the feature module.

Sub-routes:

Path	Component	Purpose
analyzer (default)	AnalyzerComponent	Inference UI — file/camera input, bounding box canvas
vault	HistoryComponent	Batch history vault with canvas thumbnails
chat	ChatbotComponent	Industrial Intelligence Portal (n8n chat proxy)

Services (src/src.palm.vision/services/)

InferenceService — Local WASM inference:

• analyze(file, batchId?, mode) → Observable<InferenceFrame> — preprocesses image → posts tensor to Web Worker → emits result
• preprocessImage(dataUrl) — resizes to 640×640 on canvas, converts RGBA→CHW, normalizes [0.0, 1.0] → Float32Array [1, 3, 640, 640]
• results$: Subject<InferenceFrame> — hot stream of all completed frames
• queueDepth$: BehaviorSubject<number> — pending worker frame count
• pendingMap: Map<string, fn> — in-memory frameId → observer resolver

RemoteInferenceService — WebSocket bridge to NestJS backend:

• analyze(file, sourceLabel?, batchId?) → Observable<InferenceFrame> — sends PalmVision:analyze via FIS envelope
• getHistory() → Observable<any[]> — History:getAll
• deleteRecord(archiveId) → Observable<{ deleted: boolean }> — History:delete
• clearHistory() → Observable<{ deleted: number }> — History:clearAll
• getImage(archiveId) → Observable<{ archiveId, image_data }> — PalmHistory:GetImage
• saveExternalResult(payload) → Observable<any> — PalmHistory:SaveExternalResult

All calls are wrapped in the FIS envelope and routed via DpService.stream().

Connection config loaded from src/src.palm.vision/config/config.json:

{ "connection": { "uacp": "http://localhost:3000", "uacp_ws": "ws://localhost:3000/socket.io", "uacpEmulation": "on" } }

State (src/src.palm.vision/store/)

VisionStateModel:

{
  items: any[];                        // History records from server
  loading: boolean;
  expandedBatchIds: string[];          // Expanded accordion groups
  currentInference: InferenceFrame | null;
  batchFrames: InferenceFrame[];       // Current batch results
  selectedFrameIndex: number | null;
}

Selectors: VisionState.items, VisionState.loading, VisionState.expandedBatchIds, VisionState.currentInference

Actions (vision.actions.ts):

Action	Payload	Effect
SubmitBatchAnalysis	{ files: File[]; mode: 'local-onnx' \| 'local-tflite' \| 'remote' }	Run batch inference; local results persisted via saveExternalResult before vault display
ToggleBatchGroup	{ batchId: string }	Expand/collapse history accordion
LoadGroupImages	{ batchId: string }	Lazy-load archived images for a batch
LoadHistory	—	Fetch last 50 records from SQLite
DeleteHistoryRecord	{ id: string }	Delete record + disk image
ClearAllHistory	—	Wipe all records

Key submitBatchAnalysis behaviour: generates a shared batchId = UUID, fans out per-file streams via merge(), collects via toArray(), then dispatches LoadHistory. In local-onnx/local-tflite mode each frame is first persisted to the backend via saveExternalResult() (with timeout(5000) + catchError fallback) before being committed to the batch.

Components

AnalyzerComponent — Three-mode inference UI:

• Engine selector: local-onnx (ONNX WASM), local-tflite (TFLite WASM), remote (NestJS server)
• Input: drag-and-drop file zone or live webcam (getUserMedia, environment-facing, 640×640)
• Batch carousel: prev/next navigation across batchFrames
• Canvas overlay via renderPredictionsWithBoxes(frame) — uses norm_box normalized coords preferentially, falls back to box pixel coords
• MPOB color palette: Ripe #4caf50, Unripe #ff9800, Underripe #ffeb3b, Overripe #9c27b0, Abnormal #f44336, Empty_Bunch #607d8b

HistoryComponent — Batch vault:

• Groups items by batch_id into BatchGroup[] via combineLatest([items$, expandedBatchIds$])
• @ViewChildren('thumbCanvas') — canvas thumbnails rendered via renderThumbnailWithBoxes() using norm_box coordinates
• paintAllVisibleCanvases() with setTimeout(0) deferral; data-archive-id attribute maps canvas elements to data items
• Mode badge variants: ONNX, TFLite, Server

ChatbotComponent — Thin wrapper around angularlib/chat/chat.component with title "Industrial Intelligence Portal".

Web Worker (src/src.palm.vision/workers/inference.worker.ts)

Receives { frameId, batchId, imageDataUrl, tensor: ArrayBuffer (transferred), processingStart, mode }.

• ONNX path (local-onnx): Loads ONNX session once from /assets/models/onnx/best.onnx; runs via onnxruntime-web; output shape [1, N, 6] (x, y, x, y, conf, classIdx); filters at confidence ≥ 0.25.
• TFLite path (local-tflite): Dynamically imports /assets/tflite-wasm/tflite_web_api_client.js; initializes TFLiteWebModelRunner for /assets/models/tflite/best_float16.tflite; converts CHW→HWC before upload; model includes internal NMS; output [1, 300, 6]; filters at confidence ≥ 0.20; maps [ymin, xmin, ymax, xmax] → [nx1, ny1, nx2, ny2].

Returns InferenceFrame-shaped postMessage correlated by frameId.

Key Interfaces

interface DetectionResult {
  bunch_id: number;
  class: string;              // MPOB class name
  confidence: number;         // [0, 1]
  is_health_alert: boolean;   // true if Abnormal | Empty_Bunch
  box: [x1, y1, x2, y2];     // absolute pixel coords
  norm_box?: [nx1, ny1, nx2, ny2]; // normalized [0,1] coords
}

interface InferenceFrame {
  frameId: string;
  batchId?: string;
  imageDataUrl: string;
  detections: DetectionResult[];
  inference_ms: number;
  processing_ms: number;
  total_count: number;
  industrial_summary: Record<string, number>;
  source: 'wasm-local' | 'remote' | 'n8n';
}

Shared In-Source Dependencies (src/dependencies/)

Alias	Path	Contents
angularlib/*	src/dependencies/angularlib/	UI components (forms, dialogs, chat), auth, UIState, ChatState
dp-ui/*	src/dependencies/dp-ui/	DpService, NgxSocketService, DPState, FIS message models
fis/*	src/dependencies/fis/	Domain modules (leave, tender, approval), MetadataState
fis-commons/*	src/dependencies/fis-commons/	CDN-hosted shared utilities

Models & WASM Assets

• src/assets/models/onnx/best.onnx — YOLOv8 ONNX model for browser ONNX WASM inference
• src/assets/models/tflite/best_float16.tflite — TFLite model (loaded by worker in local-tflite mode)
• src/assets/wasm/ — ONNX Runtime Web JS + WASM bundles
• src/assets/tflite-wasm/ — TensorFlow Lite WASM runtime (tflite_web_api_client.js + WASM)

Multi-Build Strategy

angular.json defines four production configurations that swap menu and assets via fileReplacements:

Config	Output	Swaps
production	dist/rc	—
leave-prod	dist/leave	menu.ts → menu.leave.ts, leave assets
quotation-prod	dist/quotation	menu.ts → menu.quotation.ts, quotation assets
maf-quot-prod	dist/maf/quotation	MAF quotation assets

Development build uses a mock socket service (dp.service.t.ts) for offline development.

PWA

Service worker registered immediately (registerImmediately) via ngsw-config.json. PWA install prompt handled in AppComponent (mobile platforms only). Three language packs: en_US, ms_MY, zh_Hans.

CORS / Connection

Frontend connects to NestJS backend at https://localhost:3000 (configurable via src/config/config.json). Backend CORS whitelist is hardcoded in server-desktop/src/main.ts and server-android/src/main.ts — add new device IPs there.