# Developer Guide: Key Components

This document describes the major classes and modules that form the core of the Asset Processor Tool.

## `ProcessingEngine` (`processing_engine.py`)

The `ProcessingEngine` class is the new core component responsible for executing the asset processing pipeline for a *single* input asset. Unlike the older `AssetProcessor`, this engine operates *solely* based on a complete `SourceRule` object provided to its `process()` method and the static `Configuration` object passed during initialization. It contains no internal prediction, classification, or fallback logic. Its key responsibilities include:

*   Setting up and cleaning up a temporary workspace for processing.
*   Extracting or copying input files to the workspace.
*   Processing files based on the explicit rules and predicted values contained within the input `SourceRule`.
*   Processing texture maps (resizing, format/bit depth conversion, inversion, stats calculation) using parameters from the `SourceRule` or static `Configuration`.
*   Merging channels based on rules defined in the static `Configuration` and parameters from the `SourceRule`.
*   Generating the `metadata.json` file containing details about the processed asset, incorporating information from the `SourceRule`.
*   Organizing the final output files into the structured library directory.

## `AssetProcessor` (`asset_processor.py`)

The `AssetProcessor` class is the older processing engine. It is kept in the codebase for reference but is **no longer used** in the main processing flow orchestrated by `main.py` or the GUI. Its original role was similar to the new `ProcessingEngine`, but it included internal prediction, classification, and fallback logic based on hierarchical rules and static configuration.

## `Rule Structure` (`rule_structure.py`)

This module defines the data structures used to represent the hierarchical processing rules:

*   `SourceRule`: A dataclass representing rules applied at the source level. It contains nested `AssetRule` objects.
*   `AssetRule`: A dataclass representing rules applied at the asset level. It contains nested `FileRule` objects.
*   `FileRule`: A dataclass representing rules applied at the file level.

These classes hold specific rule parameters (e.g., `supplier_identifier`, `asset_type`, `asset_type_override`, `item_type`, `item_type_override`, `target_asset_name_override`). Attributes like `asset_type` and `item_type_override` now use string types, which are validated against centralized lists in `config.py`. These structures support serialization (Pickle, JSON) to allow them to be passed between different parts of the application, including across process boundaries.

## `Configuration` (`configuration.py`)

The `Configuration` class manages the tool's settings. It is responsible for:

*   Loading the core default settings defined in `config.py`.
*   Loading the supplier-specific rules from a selected preset JSON file (`Presets/*.json`).
*   Merging the core settings and preset rules into a single, unified configuration object.
*   Validating the loaded configuration to ensure required settings are present.
*   Pre-compiling regular expression patterns defined in the preset for efficient file classification by the `PredictionHandler`.

An instance of the `Configuration` class is typically created once per application run (or per processing batch) and passed to the `ProcessingEngine`.

## `MainWindow` (`gui/main_window.py`)

The `MainWindow` class is the main application window for the Graphical User Interface (GUI). It handles the overall UI layout and user interaction:

*   Defines the main application window structure and layout using PySide6 widgets.
*   Arranges the Preset Editor panel (left) and the Unified Hierarchical View (right).
*   Setting up the menu bar, including the "View" menu for toggling the Log Console.
*   Connecting user interactions (button clicks, drag-and-drop events, edits in the Unified View) to corresponding methods (slots) within the `MainWindow` or other handler classes.
*   Managing the display of application logs in the UI console using a custom `QtLogHandler`.
*   Interacting with background handlers (`ProcessingHandler`, `PredictionHandler`) via Qt signals and slots to ensure thread-safe updates to the UI during long-running operations.
*   Receiving the initial `SourceRule` hierarchy from the `PredictionHandler` and populating the `UnifiedViewModel`.
*   Sending the final, potentially user-modified, `SourceRule` list to `main.py` to initiate processing via the `ProcessingEngine`.

## `Unified View Model` (`gui/unified_view_model.py`)

The `UnifiedViewModel` implements a `QAbstractItemModel` for use with Qt's model-view architecture. It is specifically designed to:

*   Wrap a list of `SourceRule` objects and expose their hierarchical structure (Source -> Asset -> File) to a `QTreeView` (the Unified Hierarchical View).
*   Provide methods (`data`, `index`, `parent`, `rowCount`, `columnCount`, `flags`, `setData`) required by `QAbstractItemModel` to allow the `QTreeView` to display the rule hierarchy and support inline editing of specific attributes (e.g., `supplier_override`, `asset_type_override`, `item_type_override`, `target_asset_name_override`).
*   Handle the direct restructuring of the underlying `SourceRule` hierarchy when `target_asset_name_override` is edited, including moving `FileRule`s and managing `AssetRule` creation/deletion.
*   Determine row background colors based on the `asset_type` and `item_type`/`item_type_override` using color metadata from `config.py`.
*   Hold the `SourceRule` data that is the single source of truth for the GUI's processing rules.

## `Delegates` (`gui/delegates.py`)

This module contains custom `QStyledItemDelegate` implementations used by the Unified Hierarchical View (`QTreeView`) to provide inline editors for specific data types or rule attributes. Examples include delegates for:

*   `ComboBoxDelegate`: For selecting from predefined lists of allowed asset and file types, sourced from `config.py`.
*   `LineEditDelegate`: For free-form text editing, such as the `target_asset_name_override`.
*   `SupplierSearchDelegate`: A new delegate for the "Supplier" column. It provides a `QLineEdit` with auto-completion suggestions loaded from `config/suppliers.json` and handles adding/saving new suppliers.

These delegates handle the presentation and editing of data within the tree view cells, interacting with the `UnifiedViewModel` to get and set data.

## `ProcessingHandler` (`gui/processing_handler.py`)

The `ProcessingHandler` class is designed to run in a separate `QThread` within the GUI. Its purpose is to manage the execution of the main asset processing pipeline using the **`ProcessingEngine`** in the background, preventing the GUI from freezing. It:

*   Manages a `concurrent.futures.ProcessPoolExecutor` to run individual asset processing tasks (`ProcessingEngine.process()`) in separate worker processes.
*   Submits processing tasks to the pool, passing the relevant `SourceRule` object and `Configuration` instance to the `ProcessingEngine`.
*   Monitors task completion and communicates progress, status updates, and results back to the `MainWindow` using Qt signals.
*   Handles the execution of optional Blender scripts via subprocess calls after asset processing is complete.
*   Provides logic for cancelling ongoing processing tasks.

## `PredictionHandler` (`gui/prediction_handler.py`)

The `PredictionHandler` class also runs in a separate `QThread` in the GUI. It is responsible for generating the initial `SourceRule` hierarchy with predicted values based on the input files and the selected preset. It:

*   Takes an input source identifier (path), a list of files within that source, and the selected preset name as input.
*   Uses logic (including accessing preset rules and `config.py`'s allowed types) to analyze files and predict initial values for overridable fields in the `SourceRule`, `AssetRule`, and `FileRule` objects (e.g., `supplier_identifier`, `asset_type`, `item_type`, `target_asset_name_override`).
*   Constructs a `SourceRule` hierarchy for the single input source.
*   Emits a signal (`rule_hierarchy_ready`) with the input source identifier and the generated `SourceRule` object (within a list) to the `MainWindow` for accumulation and eventual population of the `UnifiedViewModel`.

## `ZipHandler` (`monitor.py`)

The `ZipHandler` is a custom event handler used by the `monitor.py` script, built upon the `watchdog` library. It is responsible for:

*   Detecting file system events, specifically the creation of new `.zip` files, in the monitored input directory.
*   Validating the filename format of detected ZIPs to extract the intended preset name.
*   Triggering the main asset processing logic (`main.run_processing`) for valid new ZIP files.
*   Managing the movement of processed source ZIP files to 'processed' or 'error' directories.

These key components work together to provide the tool's functionality, separating concerns and utilizing concurrency for performance and responsiveness. The `SourceRule` object serves as a clear data contract between the GUI/prediction layer and the processing engine.