From 72334795da54573691cf3aecd135c34e8fd54f65 Mon Sep 17 00:00:00 2001
From: jack <jack@isensecloud.com>
Date: Thu, 11 Jun 2026 12:15:00 -0700
Subject: [PATCH] refactor: reorganize backend modules into sub-packages for
 models, data, visualization, wafer, and controllers

---
 src/pygui/__main__.py                         | 12 +++----
 src/pygui/backend/__init__.py                 | 33 ++++++++++++++++++-
 src/pygui/backend/controllers/__init__.py     |  6 ++++
 .../{ => controllers}/device_controller.py    |  8 ++---
 .../{ => controllers}/session_controller.py   | 18 +++++-----
 src/pygui/backend/crypto/__init__.py          |  2 ++
 .../backend/{ => crypto}/crypto_helper.py     |  0
 src/pygui/backend/data/__init__.py            | 16 +++++++++
 .../backend/{ => data}/csv_file_metadata.py   |  0
 src/pygui/backend/{ => data}/csv_recorder.py  |  4 +--
 src/pygui/backend/{ => data}/data_records.py  |  4 +--
 src/pygui/backend/{ => data}/data_segment.py  |  0
 src/pygui/backend/{ => data}/file_browser.py  |  4 +--
 .../backend/{ => data}/local_settings.py      |  0
 .../{ => data}/local_settings_model.py        |  2 +-
 src/pygui/backend/models/__init__.py          | 19 +++++++++++
 src/pygui/backend/{ => models}/data_model.py  |  0
 src/pygui/backend/{ => models}/frame.py       |  0
 .../backend/{ => models}/frame_player.py      |  4 +--
 src/pygui/backend/{ => models}/frame_stats.py |  0
 .../backend/{ => models}/sensor_editor.py     |  0
 .../backend/{ => models}/session_model.py     |  8 ++---
 .../{ => models}/stability_detector.py        |  0
 .../{ => models}/threshold_classifier.py      |  0
 src/pygui/backend/visualization/__init__.py   | 11 +++++++
 .../{ => visualization}/contour_models.py     |  0
 .../backend/{ => visualization}/graph_view.py |  0
 .../{ => visualization}/marching_squares.py   |  2 +-
 .../{ => visualization}/rbf_heatmap.py        |  0
 .../{ => visualization}/wafer_map_item.py     |  4 +--
 src/pygui/backend/wafer/__init__.py           | 10 ++++++
 .../backend/{ => wafer}/wafer_layouts.py      |  4 +--
 .../backend/{ => wafer}/zwafer_models.py      |  0
 .../backend/{ => wafer}/zwafer_parser.py      |  2 +-
 src/pygui/serialcomm/device_service.py        |  2 +-
 src/pygui/serialcomm/stream_reader.py         |  2 +-
 tests/test_csv_recorder.py                    | 10 +++---
 tests/test_data_records.py                    |  2 +-
 tests/test_frame_player.py                    |  4 +--
 tests/test_frame_stats.py                     |  2 +-
 tests/test_rbf_heatmap.py                     |  2 +-
 tests/test_sensor_editor.py                   |  2 +-
 tests/test_session_model.py                   |  6 ++--
 tests/test_stability_detector.py              |  2 +-
 tests/test_stream_reader.py                   |  2 +-
 tests/test_threshold_classifier.py            |  2 +-
 tests/test_wafer_layouts.py                   |  4 +--
 47 files changed, 155 insertions(+), 60 deletions(-)
 create mode 100644 src/pygui/backend/controllers/__init__.py
 rename src/pygui/backend/{ => controllers}/device_controller.py (98%)
 rename src/pygui/backend/{ => controllers}/session_controller.py (95%)
 create mode 100644 src/pygui/backend/crypto/__init__.py
 rename src/pygui/backend/{ => crypto}/crypto_helper.py (100%)
 create mode 100644 src/pygui/backend/data/__init__.py
 rename src/pygui/backend/{ => data}/csv_file_metadata.py (100%)
 rename src/pygui/backend/{ => data}/csv_recorder.py (94%)
 rename src/pygui/backend/{ => data}/data_records.py (94%)
 rename src/pygui/backend/{ => data}/data_segment.py (100%)
 rename src/pygui/backend/{ => data}/file_browser.py (98%)
 rename src/pygui/backend/{ => data}/local_settings.py (100%)
 rename src/pygui/backend/{ => data}/local_settings_model.py (99%)
 create mode 100644 src/pygui/backend/models/__init__.py
 rename src/pygui/backend/{ => models}/data_model.py (100%)
 rename src/pygui/backend/{ => models}/frame.py (100%)
 rename src/pygui/backend/{ => models}/frame_player.py (92%)
 rename src/pygui/backend/{ => models}/frame_stats.py (100%)
 rename src/pygui/backend/{ => models}/sensor_editor.py (100%)
 rename src/pygui/backend/{ => models}/session_model.py (80%)
 rename src/pygui/backend/{ => models}/stability_detector.py (100%)
 rename src/pygui/backend/{ => models}/threshold_classifier.py (100%)
 create mode 100644 src/pygui/backend/visualization/__init__.py
 rename src/pygui/backend/{ => visualization}/contour_models.py (100%)
 rename src/pygui/backend/{ => visualization}/graph_view.py (100%)
 rename src/pygui/backend/{ => visualization}/marching_squares.py (98%)
 rename src/pygui/backend/{ => visualization}/rbf_heatmap.py (100%)
 rename src/pygui/backend/{ => visualization}/wafer_map_item.py (99%)
 create mode 100644 src/pygui/backend/wafer/__init__.py
 rename src/pygui/backend/{ => wafer}/wafer_layouts.py (95%)
 rename src/pygui/backend/{ => wafer}/zwafer_models.py (100%)
 rename src/pygui/backend/{ => wafer}/zwafer_parser.py (98%)

diff --git a/src/pygui/__main__.py b/src/pygui/__main__.py
index b4f7491..5b82651 100644
--- a/src/pygui/__main__.py
+++ b/src/pygui/__main__.py
@@ -5,13 +5,13 @@ from PySide6.QtQml import QQmlApplicationEngine
 from PySide6.QtQuickControls2 import QQuickStyle
 from PySide6.QtWidgets import QApplication
 
-from pygui.backend.device_controller import DeviceController
-from pygui.backend.local_settings import LocalSettings
-from pygui.backend.local_settings_model import LocalSettingsModel
-from pygui.backend.file_browser import FileBrowser
-from pygui.backend.session_controller import SessionController
+from pygui.backend.controllers.device_controller import DeviceController
+from pygui.backend.data.local_settings import LocalSettings
+from pygui.backend.data.local_settings_model import LocalSettingsModel
+from pygui.backend.data.file_browser import FileBrowser
+from pygui.backend.controllers.session_controller import SessionController
 # Importing wafer_map_item registers the @QmlElement WaferMapItem (QML: import ISC.Wafer).
-from pygui.backend.wafer_map_item import WaferMapItem
+from pygui.backend.visualization.wafer_map_item import WaferMapItem
 
 # ===== Application Entry Point =====
 def main() -> int:
diff --git a/src/pygui/backend/__init__.py b/src/pygui/backend/__init__.py
index a22d05a..c82fea5 100644
--- a/src/pygui/backend/__init__.py
+++ b/src/pygui/backend/__init__.py
@@ -1 +1,32 @@
-# ===== Backend Package Marker =====
+# ===== Backend Package =====
+# Backward-compatible re-exports so existing callers keep working
+# while imports are migrated to the new sub-package paths.
+
+from pygui.backend.controllers.device_controller import DeviceController  # noqa: F401
+from pygui.backend.controllers.session_controller import SessionController  # noqa: F401
+
+from pygui.backend.models.frame import Frame  # noqa: F401
+from pygui.backend.models.frame_player import FramePlayer, frames_from_wafer_data  # noqa: F401
+from pygui.backend.models.frame_stats import Stats, compute_stats  # noqa: F401
+from pygui.backend.models.session_model import SessionModel  # noqa: F401
+from pygui.backend.models.data_model import TemperatureTableModel  # noqa: F401
+from pygui.backend.models.sensor_editor import SensorEditor  # noqa: F401
+from pygui.backend.models.threshold_classifier import ThresholdConfig  # noqa: F401
+from pygui.backend.models.stability_detector import StabilityDetector  # noqa: F401
+
+from pygui.backend.data.csv_recorder import CsvRecorder  # noqa: F401
+from pygui.backend.data.csv_file_metadata import CSVFileMetadata  # noqa: F401
+from pygui.backend.data.data_records import read_data_records  # noqa: F401
+from pygui.backend.data.data_segment import DataSegment  # noqa: F401
+from pygui.backend.data.file_browser import FileBrowser  # noqa: F401
+from pygui.backend.data.local_settings import LocalSettings  # noqa: F401
+from pygui.backend.data.local_settings_model import LocalSettingsModel  # noqa: F401
+
+from pygui.backend.visualization.wafer_map_item import WaferMapItem  # noqa: F401
+from pygui.backend.visualization.graph_view import GraphView  # noqa: F401
+from pygui.backend.visualization.rbf_heatmap import interpolate_field  # noqa: F401
+from pygui.backend.visualization.contour_models import ContourLine, ContourSegment  # noqa: F401
+
+from pygui.backend.wafer.zwafer_models import ZWaferData, Sensor, DataRecord  # noqa: F401
+from pygui.backend.wafer.zwafer_parser import ZWaferParser  # noqa: F401
+from pygui.backend.wafer.wafer_layouts import load_layout, available_families  # noqa: F401
diff --git a/src/pygui/backend/controllers/__init__.py b/src/pygui/backend/controllers/__init__.py
new file mode 100644
index 0000000..188bbe8
--- /dev/null
+++ b/src/pygui/backend/controllers/__init__.py
@@ -0,0 +1,6 @@
+# ===== Controllers Sub-package =====
+from pygui.backend.controllers.device_controller import DeviceController
+from pygui.backend.controllers.session_controller import SessionController
+
+__all__ = ["DeviceController", "SessionController"]
+    
\ No newline at end of file
diff --git a/src/pygui/backend/device_controller.py b/src/pygui/backend/controllers/device_controller.py
similarity index 98%
rename from src/pygui/backend/device_controller.py
rename to src/pygui/backend/controllers/device_controller.py
index 3f44d96..fd0840d 100644
--- a/src/pygui/backend/device_controller.py
+++ b/src/pygui/backend/controllers/device_controller.py
@@ -15,9 +15,9 @@ from typing import Any, Optional
 
 from PySide6.QtCore import QObject, Property, Qt, Signal, Slot
 
-from pygui.backend.data_model import TemperatureTableModel
-from pygui.backend.graph_view import GraphView
-from pygui.backend.local_settings import LocalSettings
+from pygui.backend.models.data_model import TemperatureTableModel
+from pygui.backend.visualization.graph_view import GraphView
+from pygui.backend.data.local_settings import LocalSettings
 from pygui.serialcomm.data_parser import (
     convert_to_temperatures,
     parse_binary_data,
@@ -26,7 +26,7 @@ from pygui.serialcomm.data_parser import (
 )
 from pygui.serialcomm.device_service import DeviceService
 from pygui.serialcomm.serial_port import WaferInfo
-from pygui.backend.session_controller import SessionController
+from pygui.backend.controllers.session_controller import SessionController
 # import pygui.backend.wafer_map_item
 
 stream_controller = SessionController()
diff --git a/src/pygui/backend/session_controller.py b/src/pygui/backend/controllers/session_controller.py
similarity index 95%
rename from src/pygui/backend/session_controller.py
rename to src/pygui/backend/controllers/session_controller.py
index 23d7eae..36425a1 100644
--- a/src/pygui/backend/session_controller.py
+++ b/src/pygui/backend/controllers/session_controller.py
@@ -5,15 +5,15 @@ from typing import Any, Optional
 
 from PySide6.QtCore import QObject, Property, QTimer, Qt, Signal, Slot
 
-from pygui.backend.csv_recorder import CsvRecorder
-from pygui.backend.frame import Frame
-from pygui.backend.frame_player import FramePlayer, frames_from_wafer_data
-from pygui.backend.session_model import SessionModel
-from pygui.backend.threshold_classifier import ThresholdConfig
-from pygui.backend.zwafer_models import Sensor
-from pygui.backend.zwafer_parser import ZWaferParser
+from pygui.backend.data.csv_recorder import CsvRecorder
+from pygui.backend.models.frame import Frame
+from pygui.backend.models.frame_player import FramePlayer, frames_from_wafer_data
+from pygui.backend.models.session_model import SessionModel
+from pygui.backend.models.threshold_classifier import ThresholdConfig
+from pygui.backend.wafer.zwafer_models import Sensor
+from pygui.backend.wafer.zwafer_parser import ZWaferParser
 from pygui.serialcomm.stream_reader import StreamReader
-from pygui.backend.sensor_editor import SensorEditor
+from pygui.backend.models.sensor_editor import SensorEditor
 
 log = logging.getLogger(__name__)
 
@@ -155,7 +155,7 @@ class SessionController(QObject):
     # ---- review: file load + playback ----
     @Slot(str)
     def loadFile(self, file_path: str) -> None:
-        from pygui.backend.data_records import is_official_csv, read_data_records, read_official_csv
+        from pygui.backend.data.data_records import is_official_csv, read_data_records, read_official_csv
 
         sensors: list[Sensor] = []
         frames = []
diff --git a/src/pygui/backend/crypto/__init__.py b/src/pygui/backend/crypto/__init__.py
new file mode 100644
index 0000000..30cbc74
--- /dev/null
+++ b/src/pygui/backend/crypto/__init__.py
@@ -0,0 +1,2 @@
+# ===== Crypto Sub-package =====
+from pygui.backend.crypto.crypto_helper import *  # noqa: F403
diff --git a/src/pygui/backend/crypto_helper.py b/src/pygui/backend/crypto/crypto_helper.py
similarity index 100%
rename from src/pygui/backend/crypto_helper.py
rename to src/pygui/backend/crypto/crypto_helper.py
diff --git a/src/pygui/backend/data/__init__.py b/src/pygui/backend/data/__init__.py
new file mode 100644
index 0000000..b123679
--- /dev/null
+++ b/src/pygui/backend/data/__init__.py
@@ -0,0 +1,16 @@
+# ===== Data Sub-package =====
+from pygui.backend.data.csv_recorder import CsvRecorder
+from pygui.backend.data.csv_file_metadata import CSVFileMetadata
+from pygui.backend.data.data_records import read_data_records, is_official_csv, read_official_csv
+from pygui.backend.data.data_segment import DataSegment
+from pygui.backend.data.file_browser import FileBrowser
+from pygui.backend.data.local_settings import LocalSettings
+from pygui.backend.data.local_settings_model import LocalSettingsModel
+
+__all__ = [
+    "CsvRecorder", "CSVFileMetadata",
+    "read_data_records", "is_official_csv", "read_official_csv",
+    "DataSegment",
+    "FileBrowser",
+    "LocalSettings", "LocalSettingsModel",
+]
diff --git a/src/pygui/backend/csv_file_metadata.py b/src/pygui/backend/data/csv_file_metadata.py
similarity index 100%
rename from src/pygui/backend/csv_file_metadata.py
rename to src/pygui/backend/data/csv_file_metadata.py
diff --git a/src/pygui/backend/csv_recorder.py b/src/pygui/backend/data/csv_recorder.py
similarity index 94%
rename from src/pygui/backend/csv_recorder.py
rename to src/pygui/backend/data/csv_recorder.py
index 8e123ed..0e6a91c 100644
--- a/src/pygui/backend/csv_recorder.py
+++ b/src/pygui/backend/data/csv_recorder.py
@@ -5,8 +5,8 @@ from pathlib import Path
 from typing import Optional, TextIO
 
 
-from pygui.backend.frame import Frame
-from pygui.backend.zwafer_models import Sensor
+from pygui.backend.models.frame import Frame
+from pygui.backend.wafer.zwafer_models import Sensor
 
 class CsvRecorder:
     def __init__(self) -> None:
diff --git a/src/pygui/backend/data_records.py b/src/pygui/backend/data/data_records.py
similarity index 94%
rename from src/pygui/backend/data_records.py
rename to src/pygui/backend/data/data_records.py
index 7b5ffef..2117c87 100644
--- a/src/pygui/backend/data_records.py
+++ b/src/pygui/backend/data/data_records.py
@@ -2,7 +2,7 @@
 from __future__ import annotations
 from pathlib import Path
 
-from pygui.backend.zwafer_models import DataRecord, Sensor
+from pygui.backend.wafer.zwafer_models import DataRecord, Sensor
 
 def read_data_records(file_path: str) -> list[DataRecord]:
     records: list[DataRecord] = []
@@ -40,7 +40,7 @@ def is_official_csv(file_path: str) -> bool:
 
 def read_official_csv(file_path: str) -> tuple[list[Sensor], list[DataRecord]]:
     """Parse the headerless official CSV: row 0 = sensor names, rows 1+ = values (no timestamp)."""
-    from pygui.backend.wafer_layouts import load_layout_for_wafer_id
+    from pygui.backend.wafer.wafer_layouts import load_layout_for_wafer_id
 
     stem = Path(file_path).stem
     wafer_id = stem.split("-")[0] if "-" in stem else stem
diff --git a/src/pygui/backend/data_segment.py b/src/pygui/backend/data/data_segment.py
similarity index 100%
rename from src/pygui/backend/data_segment.py
rename to src/pygui/backend/data/data_segment.py
diff --git a/src/pygui/backend/file_browser.py b/src/pygui/backend/data/file_browser.py
similarity index 98%
rename from src/pygui/backend/file_browser.py
rename to src/pygui/backend/data/file_browser.py
index e65537a..db70f30 100644
--- a/src/pygui/backend/file_browser.py
+++ b/src/pygui/backend/data/file_browser.py
@@ -8,8 +8,8 @@ from pathlib import Path
 from PySide6.QtCore import QObject, Property, QStandardPaths, Signal, Slot
 from PySide6.QtWidgets import QFileDialog, QMessageBox
 
-from pygui.backend.csv_file_metadata import CSVFileMetadata
-from pygui.backend.zwafer_parser import ZWaferParser
+from pygui.backend.data.csv_file_metadata import CSVFileMetadata
+from pygui.backend.wafer.zwafer_parser import ZWaferParser
 
 
 # ===== File Browser Model =====
diff --git a/src/pygui/backend/local_settings.py b/src/pygui/backend/data/local_settings.py
similarity index 100%
rename from src/pygui/backend/local_settings.py
rename to src/pygui/backend/data/local_settings.py
diff --git a/src/pygui/backend/local_settings_model.py b/src/pygui/backend/data/local_settings_model.py
similarity index 99%
rename from src/pygui/backend/local_settings_model.py
rename to src/pygui/backend/data/local_settings_model.py
index a031dcf..b4ff97d 100644
--- a/src/pygui/backend/local_settings_model.py
+++ b/src/pygui/backend/data/local_settings_model.py
@@ -6,7 +6,7 @@ from typing import Any
 
 from PySide6.QtCore import QObject, Property, QDateTime, QStandardPaths, Signal, Slot
 
-from pygui.backend.local_settings import LocalSettings
+from pygui.backend.data.local_settings import LocalSettings
 
 
 MASTER_FAMILIES = ("A", "B", "C", "D", "E", "F", "P", "X", "Z")
diff --git a/src/pygui/backend/models/__init__.py b/src/pygui/backend/models/__init__.py
new file mode 100644
index 0000000..ed3cb42
--- /dev/null
+++ b/src/pygui/backend/models/__init__.py
@@ -0,0 +1,19 @@
+# ===== Models Sub-package =====
+from pygui.backend.models.frame import Frame
+from pygui.backend.models.frame_player import FramePlayer, frames_from_wafer_data
+from pygui.backend.models.frame_stats import Stats, compute_stats
+from pygui.backend.models.session_model import SessionModel, SessionUpdate
+from pygui.backend.models.data_model import TemperatureTableModel
+from pygui.backend.models.sensor_editor import SensorEditor
+from pygui.backend.models.threshold_classifier import ThresholdConfig, classify, resolve_bounds
+from pygui.backend.models.stability_detector import StabilityDetector
+
+__all__ = [
+    "Frame", "FramePlayer", "frames_from_wafer_data",
+    "Stats", "compute_stats",
+    "SessionModel", "SessionUpdate",
+    "TemperatureTableModel",
+    "SensorEditor",
+    "ThresholdConfig", "classify", "resolve_bounds",
+    "StabilityDetector",
+]
diff --git a/src/pygui/backend/data_model.py b/src/pygui/backend/models/data_model.py
similarity index 100%
rename from src/pygui/backend/data_model.py
rename to src/pygui/backend/models/data_model.py
diff --git a/src/pygui/backend/frame.py b/src/pygui/backend/models/frame.py
similarity index 100%
rename from src/pygui/backend/frame.py
rename to src/pygui/backend/models/frame.py
diff --git a/src/pygui/backend/frame_player.py b/src/pygui/backend/models/frame_player.py
similarity index 92%
rename from src/pygui/backend/frame_player.py
rename to src/pygui/backend/models/frame_player.py
index 320ce0c..8c70811 100644
--- a/src/pygui/backend/frame_player.py
+++ b/src/pygui/backend/models/frame_player.py
@@ -1,6 +1,6 @@
 from __future__ import annotations 
-from pygui.backend.frame import Frame
-from pygui.backend.zwafer_models import ZWaferData
+from pygui.backend.models.frame import Frame
+from pygui.backend.wafer.zwafer_models import ZWaferData
 
 def frames_from_wafer_data(data: ZWaferData, records) -> list[Frame]:
     """Build Frames from parsed DataRecords (records = list[DataRecord].)"""
diff --git a/src/pygui/backend/frame_stats.py b/src/pygui/backend/models/frame_stats.py
similarity index 100%
rename from src/pygui/backend/frame_stats.py
rename to src/pygui/backend/models/frame_stats.py
diff --git a/src/pygui/backend/sensor_editor.py b/src/pygui/backend/models/sensor_editor.py
similarity index 100%
rename from src/pygui/backend/sensor_editor.py
rename to src/pygui/backend/models/sensor_editor.py
diff --git a/src/pygui/backend/session_model.py b/src/pygui/backend/models/session_model.py
similarity index 80%
rename from src/pygui/backend/session_model.py
rename to src/pygui/backend/models/session_model.py
index 4ab68ba..677d1a2 100644
--- a/src/pygui/backend/session_model.py
+++ b/src/pygui/backend/models/session_model.py
@@ -1,10 +1,10 @@
 from __future__ import annotations
 from dataclasses import dataclass
 
-from pygui.backend.frame import Frame
-from pygui.backend.frame_stats import Stats, compute_stats
-from pygui.backend.stability_detector import StabilityDetector
-from pygui.backend.threshold_classifier import ThresholdConfig, classify, resolve_bounds
+from pygui.backend.models.frame import Frame
+from pygui.backend.models.frame_stats import Stats, compute_stats
+from pygui.backend.models.stability_detector import StabilityDetector
+from pygui.backend.models.threshold_classifier import ThresholdConfig, classify, resolve_bounds
 
 @dataclass(frozen=True)
 class SessionUpdate:
diff --git a/src/pygui/backend/stability_detector.py b/src/pygui/backend/models/stability_detector.py
similarity index 100%
rename from src/pygui/backend/stability_detector.py
rename to src/pygui/backend/models/stability_detector.py
diff --git a/src/pygui/backend/threshold_classifier.py b/src/pygui/backend/models/threshold_classifier.py
similarity index 100%
rename from src/pygui/backend/threshold_classifier.py
rename to src/pygui/backend/models/threshold_classifier.py
diff --git a/src/pygui/backend/visualization/__init__.py b/src/pygui/backend/visualization/__init__.py
new file mode 100644
index 0000000..6545ceb
--- /dev/null
+++ b/src/pygui/backend/visualization/__init__.py
@@ -0,0 +1,11 @@
+# ===== Visualization Sub-package =====
+from pygui.backend.visualization.wafer_map_item import WaferMapItem
+from pygui.backend.visualization.graph_view import GraphView
+from pygui.backend.visualization.rbf_heatmap import interpolate_field
+from pygui.backend.visualization.contour_models import ContourLine, ContourSegment
+
+__all__ = [
+    "WaferMapItem", "GraphView",
+    "interpolate_field",
+    "ContourLine", "ContourSegment",
+]
diff --git a/src/pygui/backend/contour_models.py b/src/pygui/backend/visualization/contour_models.py
similarity index 100%
rename from src/pygui/backend/contour_models.py
rename to src/pygui/backend/visualization/contour_models.py
diff --git a/src/pygui/backend/graph_view.py b/src/pygui/backend/visualization/graph_view.py
similarity index 100%
rename from src/pygui/backend/graph_view.py
rename to src/pygui/backend/visualization/graph_view.py
diff --git a/src/pygui/backend/marching_squares.py b/src/pygui/backend/visualization/marching_squares.py
similarity index 98%
rename from src/pygui/backend/marching_squares.py
rename to src/pygui/backend/visualization/marching_squares.py
index b66cc6a..307d1e4 100644
--- a/src/pygui/backend/marching_squares.py
+++ b/src/pygui/backend/visualization/marching_squares.py
@@ -2,7 +2,7 @@ from typing import List, Tuple, Optional
 
 import numpy as np
 
-from pygui.backend.contour_models import ContourLine, ContourSegment
+from pygui.backend.visualization.contour_models import ContourLine, ContourSegment
 
 
 # ===== Contour Generation =====
diff --git a/src/pygui/backend/rbf_heatmap.py b/src/pygui/backend/visualization/rbf_heatmap.py
similarity index 100%
rename from src/pygui/backend/rbf_heatmap.py
rename to src/pygui/backend/visualization/rbf_heatmap.py
diff --git a/src/pygui/backend/wafer_map_item.py b/src/pygui/backend/visualization/wafer_map_item.py
similarity index 99%
rename from src/pygui/backend/wafer_map_item.py
rename to src/pygui/backend/visualization/wafer_map_item.py
index 2aa684c..b372992 100644
--- a/src/pygui/backend/wafer_map_item.py
+++ b/src/pygui/backend/visualization/wafer_map_item.py
@@ -20,8 +20,8 @@ from PySide6.QtGui import (
 from PySide6.QtQml import QmlElement
 from PySide6.QtQuick import QQuickPaintedItem
 
-from pygui.backend.rbf_heatmap import interpolate_field
-from pygui.backend.zwafer_models import Sensor
+from pygui.backend.visualization.rbf_heatmap import interpolate_field
+from pygui.backend.wafer.zwafer_models import Sensor
 
 QML_IMPORT_NAME = "ISC.Wafer"
 QML_IMPORT_MAJOR_VERSION = 1
diff --git a/src/pygui/backend/wafer/__init__.py b/src/pygui/backend/wafer/__init__.py
new file mode 100644
index 0000000..0a05117
--- /dev/null
+++ b/src/pygui/backend/wafer/__init__.py
@@ -0,0 +1,10 @@
+# ===== Wafer Sub-package =====
+from pygui.backend.wafer.zwafer_models import ZWaferData, Sensor, DataRecord
+from pygui.backend.wafer.zwafer_parser import ZWaferParser
+from pygui.backend.wafer.wafer_layouts import load_layout, available_families
+
+__all__ = [
+    "ZWaferData", "Sensor", "DataRecord",
+    "ZWaferParser",
+    "load_layout", "available_families",
+]
diff --git a/src/pygui/backend/wafer_layouts.py b/src/pygui/backend/wafer/wafer_layouts.py
similarity index 95%
rename from src/pygui/backend/wafer_layouts.py
rename to src/pygui/backend/wafer/wafer_layouts.py
index 046185c..a54d936 100644
--- a/src/pygui/backend/wafer_layouts.py
+++ b/src/pygui/backend/wafer/wafer_layouts.py
@@ -16,9 +16,9 @@ from pathlib import Path
 
 import yaml
 
-from pygui.backend.zwafer_models import Sensor
+from pygui.backend.wafer.zwafer_models import Sensor
 
-_LAYOUTS_DIR = Path(__file__).parent.parent / "assets" / "layouts"
+_LAYOUTS_DIR = Path(__file__).parent.parent.parent / "assets" / "layouts"
 
 
 def _family_name(raw_name: str) -> str:
diff --git a/src/pygui/backend/zwafer_models.py b/src/pygui/backend/wafer/zwafer_models.py
similarity index 100%
rename from src/pygui/backend/zwafer_models.py
rename to src/pygui/backend/wafer/zwafer_models.py
diff --git a/src/pygui/backend/zwafer_parser.py b/src/pygui/backend/wafer/zwafer_parser.py
similarity index 98%
rename from src/pygui/backend/zwafer_parser.py
rename to src/pygui/backend/wafer/zwafer_parser.py
index 349d036..9192529 100644
--- a/src/pygui/backend/zwafer_parser.py
+++ b/src/pygui/backend/wafer/zwafer_parser.py
@@ -2,7 +2,7 @@ from pathlib import Path
 from typing import Tuple, Optional
 from datetime import datetime, timedelta
 
-from pygui.backend.zwafer_models import ZWaferData, Sensor
+from pygui.backend.wafer.zwafer_models import ZWaferData, Sensor
 
 
 # ===== Z-Wafer CSV Parser =====
diff --git a/src/pygui/serialcomm/device_service.py b/src/pygui/serialcomm/device_service.py
index 7ecaa56..8b87ef0 100644
--- a/src/pygui/serialcomm/device_service.py
+++ b/src/pygui/serialcomm/device_service.py
@@ -11,7 +11,7 @@ from typing import Optional
 
 import serial.tools.list_ports
 
-from pygui.backend.local_settings import LocalSettings
+from pygui.backend.data.local_settings import LocalSettings
 from pygui.serialcomm.serial_port import SerialPort, WaferInfo
 
 log = logging.getLogger(__name__)
diff --git a/src/pygui/serialcomm/stream_reader.py b/src/pygui/serialcomm/stream_reader.py
index 6fa8c0f..bfff6ce 100644
--- a/src/pygui/serialcomm/stream_reader.py
+++ b/src/pygui/serialcomm/stream_reader.py
@@ -4,7 +4,7 @@ import logging
 import threading
 from typing import Callable
 
-from pygui.backend.frame import Frame
+from pygui.backend.models.frame import Frame
 
 log = logging.getLogger(__name__)
 
diff --git a/tests/test_csv_recorder.py b/tests/test_csv_recorder.py
index ceca309..2337914 100644
--- a/tests/test_csv_recorder.py
+++ b/tests/test_csv_recorder.py
@@ -1,8 +1,8 @@
-from pygui.backend.csv_recorder import CsvRecorder
-from pygui.backend.data_records import read_data_records
-from pygui.backend.frame import Frame
-from pygui.backend.zwafer_models import Sensor
-from pygui.backend.zwafer_parser import ZWaferParser
+from pygui.backend.data.csv_recorder import CsvRecorder
+from pygui.backend.data.data_records import read_data_records
+from pygui.backend.models.frame import Frame
+from pygui.backend.wafer.zwafer_models import Sensor
+from pygui.backend.wafer.zwafer_parser import ZWaferParser
 
 
 def test_recording_roundtrips_through_parser(tmp_path):
diff --git a/tests/test_data_records.py b/tests/test_data_records.py
index 25d38d5..c4a0f26 100644
--- a/tests/test_data_records.py
+++ b/tests/test_data_records.py
@@ -1,5 +1,5 @@
 """Tests for src/pygui/backend/data_records.py."""
-from pygui.backend.data_records import read_data_records
+from pygui.backend.data.data_records import read_data_records
 
 
 def test_reads_rows_after_data_marker(tmp_path):
diff --git a/tests/test_frame_player.py b/tests/test_frame_player.py
index 3ba0f6e..1b910c1 100644
--- a/tests/test_frame_player.py
+++ b/tests/test_frame_player.py
@@ -1,5 +1,5 @@
-from pygui.backend.frame import Frame
-from pygui.backend.frame_player import FramePlayer
+from pygui.backend.models.frame import Frame
+from pygui.backend.models.frame_player import FramePlayer
 
 def frames(n):
     return [Frame(seq=i, time=float(i), values=[149.0 + i])for i in range(n)]
diff --git a/tests/test_frame_stats.py b/tests/test_frame_stats.py
index d36c687..0ed5280 100644
--- a/tests/test_frame_stats.py
+++ b/tests/test_frame_stats.py
@@ -1,6 +1,6 @@
 import math
 import pytest
-from pygui.backend.frame_stats import compute_stats, Stats
+from pygui.backend.models.frame_stats import compute_stats, Stats
 
 
 def test_basic_stat():
diff --git a/tests/test_rbf_heatmap.py b/tests/test_rbf_heatmap.py
index 6239012..fb092be 100644
--- a/tests/test_rbf_heatmap.py
+++ b/tests/test_rbf_heatmap.py
@@ -1,6 +1,6 @@
 """Tests for src/pygui/backend/rbf_heatmap.py."""
 import numpy as np
-from pygui.backend.rbf_heatmap import interpolate_field, BACKEND
+from pygui.backend.visualization.rbf_heatmap import interpolate_field, BACKEND
 
 
 def test_field_shape_and_interpolates_at_sites():
diff --git a/tests/test_sensor_editor.py b/tests/test_sensor_editor.py
index 11d8d1d..5913045 100644
--- a/tests/test_sensor_editor.py
+++ b/tests/test_sensor_editor.py
@@ -1,6 +1,6 @@
 """Tests for src/pygui/backend/sensor_editor.py."""
 import pytest
-from pygui.backend.sensor_editor import SensorEditor
+from pygui.backend.models.sensor_editor import SensorEditor
 
 
 def test_replace_overrides_raw_value():
diff --git a/tests/test_session_model.py b/tests/test_session_model.py
index 8c4403b..04d9df0 100644
--- a/tests/test_session_model.py
+++ b/tests/test_session_model.py
@@ -1,6 +1,6 @@
-from pygui.backend.frame import Frame
-from pygui.backend.threshold_classifier import ThresholdConfig, BAND_HIGH, BAND_IN, BAND_LOW
-from pygui.backend.session_model import SessionModel, SessionUpdate
+from pygui.backend.models.frame import Frame
+from pygui.backend.models.threshold_classifier import ThresholdConfig, BAND_HIGH, BAND_IN, BAND_LOW
+from pygui.backend.models.session_model import SessionModel, SessionUpdate
 
 
 
diff --git a/tests/test_stability_detector.py b/tests/test_stability_detector.py
index c74aa0a..e8e0ca4 100644
--- a/tests/test_stability_detector.py
+++ b/tests/test_stability_detector.py
@@ -1,4 +1,4 @@
-from pygui.backend.stability_detector import (
+from pygui.backend.models.stability_detector import (
     StabilityDetector, STATE_IDLE, STATE_RAMP, STATE_SET,
 )
 
diff --git a/tests/test_stream_reader.py b/tests/test_stream_reader.py
index 5bf961f..5f75de7 100644
--- a/tests/test_stream_reader.py
+++ b/tests/test_stream_reader.py
@@ -1,5 +1,5 @@
 import time 
-from pygui.backend.frame import Frame
+from pygui.backend.models.frame import Frame
 from pygui.serialcomm.stream_reader import StreamReader
 
 class FakeTransport:
diff --git a/tests/test_threshold_classifier.py b/tests/test_threshold_classifier.py
index 16ab171..d29839c 100644
--- a/tests/test_threshold_classifier.py
+++ b/tests/test_threshold_classifier.py
@@ -1,6 +1,6 @@
 import math
 
-from pygui.backend.threshold_classifier import (
+from pygui.backend.models.threshold_classifier import (
     ThresholdConfig, classify, classify_all, resolve_bounds,
     BAND_IN, BAND_HIGH, BAND_LOW
 )
diff --git a/tests/test_wafer_layouts.py b/tests/test_wafer_layouts.py
index fe0f629..e558daa 100644
--- a/tests/test_wafer_layouts.py
+++ b/tests/test_wafer_layouts.py
@@ -1,7 +1,7 @@
 """Tests for src/pygui/backend/wafer_layouts.py."""
 import pytest
-from pygui.backend.wafer_layouts import load_layout, available_families
-from pygui.backend.zwafer_models import Sensor
+from pygui.backend.wafer.wafer_layouts import load_layout, available_families
+from pygui.backend.wafer.zwafer_models import Sensor
 
 
 def test_lists_bundled_families():