# Core Components Distinction Guide

This document aims to clarify the distinction between the different "Core" components within the **SecInterp** project to avoid confusion for both human developers and AI agents.

## ⚠️ The Fundamental Distinction

Two "Core" entities coexist in this development environment:

1.  **SecInterp Core** (The Project's Kernel):
    *   **Location**: `/core` directory within the project root.
    *   **Purpose**: Contains pure business logic, geological algorithms, processing services, and domain models (DTOs) specific to SecInterp.
    *   **Current State**: **Decoupled**. As of version 2.8.0, this module has been sanitized to have no direct dependencies on QGIS live classes during heavy processing (Thread-Safe).

2.  **QGIS Core** (The QGIS API):
    *   **Reference**: `qgis.core` Python package.
    *   **Purpose**: Provides the underlying geospatial infrastructure (geometries, layers, projects, CRS).
    *   **Interaction**: SecInterp uses `qgis.core` to extract data in the main thread, but the **SecInterp Core** processes this data using agnostic types (WKT, dictionaries, primitives).

---

## 🧭 Guidelines for Developers and AI

To maintain architectural integrity, follow these directives:

### 1. Do not assume "Core" always means QGIS
If asked to "review the core", it almost exclusively refers to the `/core` directory of this plugin. Do not attempt to search for or modify internal files of the QGIS engine.

### 2. Data Boundaries (Decoupling)
*   **Inside `/core`**: Agnostic domain types must be used. Avoid instantiating `QgsVectorLayer` or accessing `QgsProject.instance()` within kernel services. Use `DomainGeometry` (WKT) and attribute dictionaries.
*   **Inside `/gui`**: This is where the translation between the real QGIS API (`qgis.core`) and the **SecInterp Core** takes place. Geometries are extracted and DTOs are prepared here.

### 3. File Naming and Imports
*   **Local Files**: Files in `core/` (e.g., `core/services/geology_service.py`) are the **SecInterp Brain**.
*   **External API**: Imports starting with `qgis.core`, `qgis.gui`, or `qgis.utils` are **External Dependencies**.
*   **Naming Rule**: In discussions or code comments, use "Internal Core" to refer to `/core` and "PyQGIS API" for the software's API.

### 4. The "Extract-then-Compute" Pattern
To avoid future complications, the data flow **MUST** follow this pattern:
1.  **GUI/Task Interface Layer**: Receives QGIS objects (`QgsVectorLayer`, `QgsFeature`). Extracts what is necessary (WKT geometry, attribute dictionaries).
2.  **Core Layer**: Receives only the extracted data (strings, dicts, floats). Performs heavy geometric calculations.
3.  **Result**: The Core returns DTOs (Data Transfer Objects) defined in `core/types.py`. The GUI layer is responsible for converting these back to QGIS layers if necessary.

### 5. Golden Rules for Thread-Safety
*   **Prohibited**: Importing `qgis.gui` inside `core/`. Background threads will crash if they attempt to touch any widget or window.
*   **Restriction**: Minimize the use of `qgis.core` inside `core/`. While some classes like `QgsGeometry` are thread-safe, it is preferable to operate on WKT to guarantee total independence.
*   **Application Context**: Never use `iface` or `QgsProject.instance()` inside `core/`. If project data is needed, pass it as pre-extracted arguments.

---

## 🧪 Differentiated Testing Strategy

*   **Core Tests (`tests/core/`)**: Must be able to run without a full QGIS installation. They use lightweight mocks. They are the thermometer of geological logic.
*   **Integration Tests (`tests/integration/`)**: Require real QGIS. They test that our "Core" correctly communicates with the "QGIS API".

---

## 🛠️ Decoupling Summary (January 2026)

A major effort has been completed to ensure:
*   `GeologyService` does not use live QGIS layers in its processing method.
*   `DrillholeService` uses dictionaries instead of `QgsFeature` objects during trace calculation.
*   3D projection logic accepts tuples and primitive types.

**In summary: Keep our Core "pure". Treat QGIS as an external service provider. Do not let the roots of one enter the logic of the other.**