update readme

README.md

@@ -2,6 +2,36 @@
 
 Small PySide6 + Qt Quick application scaffold for the `ISenseCloud` desktop UI shell.
 
+## Key App Features
+
+The `ISenseCloud` application provides a real-time monitor and analysis dashboard for silicon wafer temperature profiles:
+
+- **Real-Time Data Streaming & Coalescing**: Decodes binary frame streams from thermal sensors over serial/COM connections at ~20 Hz with low CPU overhead.
+- **RBF Heatmap Interpolation**: A Radial Basis Function (RBF) interpolation engine paints a smooth 2D temperature gradient across the wafer surface based on physical sensor locations.
+- **Interactive Review & Playback**: A `FramePlayer` component supports variable-speed playback (play, pause, step, seek) of recorded runs.
+- **Interactive Trend Charts**: Renders multi-series temperature trends using a custom QtQuick painted item (`GraphQuickItem`) with automatic scaling, custom legends, and grid layouts.
+- **Tabular Data Inspection**: Direct inspection of tabular dataset grids for frame-by-frame diagnostic checkups.
+- **Custom Safety Limits & Thresholds**: Configurable alarm thresholds and set-points with automatic alerts when temperatures diverge from normal boundaries.
+
+### App Showcase
+![ISenseCloud UI displaying successful connection on COM6](image-1.png)
+*Figure 1: Main Status Dashboard displaying successful connection, active serial communications, and automated logging terminal.*
+
+> [!NOTE]
+> **Take Screenshots for Visual Placeholders:**
+> - **Wafer Heatmap Tab**: Take a screenshot of the Wafer Map tab showing the radial heatmap interpolation, save it to `docs/design/wafer_heatmap_tab.png` and add it here.
+> - **Temperature Trend Graph**: Take a screenshot of the Graph tab plotting multi-sensor trend lines, save it to `docs/design/temp_trend_tab.png` and add it here.
+
+## Key Architectural & Design Decisions
+
+During the refactoring from the flat-layout prototype (`SettingTab` branch) to the unified package application (`main`), the following structural changes were made:
+
+1. **Package Layout Restructuring**: Reorganized flat imports into a clean `src/` layout under `pygui.*` sub-packages (`controllers/`, `models/`, `data/`, `visualization/`, `wafer/`) for better module isolation.
+2. **QML Component Decoupling**: Monolithic pages were refactored into reusable component blocks (e.g., `ReadoutPanel.qml`, `WaferMapView.qml`, `TransportBar.qml` under `src/pygui/ISC/Tabs/components/`), easing tab maintenance.
+3. **Decoupled Controller Architecture**: Introduced QML-bound controllers (`DeviceController`, `SessionController`) acting as bridges between UI triggers and backend model states (`FramePlayer`, `SessionModel`), keeping UI files strictly visual.
+4. **Robust Slot Error Boundaries**: Decorated QML-callable slots with a custom `@slot_error_boundary` wrapper to intercept runtime errors gracefully without terminating the Qt environment.
+5. **Modernized Rendering Engine**: Replaced outdated contour algorithms with Radial Basis Function (RBF) interpolation (`rbf_heatmap.py`) to render high-fidelity, real-time thermal profiles.
+
 ## Requirements
 
 - Python 3.11+ (tested with Python 3.14 in this workspace)
@@ -28,10 +58,10 @@ pip install -e .            # install the `pygui` package (src/ layout) in edita
 
 ## Run
 
+### Launch PySide6 QML App
 ```bash
 make run
 ```
-
 This launches the Qt window and loads the `ISC` QML module from `src/pygui/ISC/Main.qml`.
 
 ## Development
@@ -78,6 +108,41 @@ The application lives under a `src/` layout as the `pygui` package:
 - `tests/`: pytest suite.
 - `packaging/`: PyInstaller spec (`isc.spec`) and app icons.
 
+## Architecture
+
+```
+┌────────────────────────────────────────────────────────────┐
+│                      QML Layer (src/pygui/ISC/)            │
+│  HomePage.qml  ─  WaferMapTab.qml  ─  DataTab.qml         │
+│  StatusTab.qml  ─  SettingsTab.qml  ─  components/*        │
+└─────────────────────────┬──────────────────────────────────┘
+                          │  Q_PROPERTY / @Slot / Signal
+┌─────────────────────────▼──────────────────────────────────┐
+│                Controller Layer (backend/controllers/)      │
+│  DeviceController  ─  SessionController                    │
+│  (serial ops, status)  (streaming, playback)                │
+└─────────────────────────┬──────────────────────────────────┘
+                          │
+┌─────────────────────────▼──────────────────────────────────┐
+│                  Model Layer (backend/models/)              │
+│  FramePlayer  ─  SessionModel  ─  ReplayStatsTracker       │
+│  ThresholdClassifier  ─  SensorEditor  ─  ClusterAverage   │
+│  TemperatureTableModel                                     │
+└─────────────────────────┬──────────────────────────────────┘
+                          │
+┌─────────────────────────▼──────────────────────────────────┐
+│              Serial / Data Layer (serialcomm/ + data/)      │
+│  SerialPort ─ DeviceService ─ StreamReader ─ data_parser   │
+│  LocalSettings ─ FileBrowser ─ CsvRecorder                 │
+└─────────────────────────┬──────────────────────────────────┘
+                          │
+┌─────────────────────────▼──────────────────────────────────┐
+│              Visualization (backend/visualization/)         │
+│  WaferMapItem  ─  GraphView  ─  TrendChartItem             │
+│  RBFHeatmap  ─  WaferMapView (QML wrapper)                 │
+└────────────────────────────────────────────────────────────┘
+```
+
 ## Window Configuration
 
 Window dimensions and constraints are defined in `src/pygui/ISC/Main.qml`: