development/docs/services/MODELS.md

@@ -0,0 +1,58 @@
+# DECNET Domain Models
+
+> [!IMPORTANT]
+> **DEVELOPMENT DISCLAIMER**: DECNET is currently in active development. The models defined in `decnet/models.py` are subject to significant changes as the framework evolves.
+
+## Overview
+
+The `decnet/models.py` file serves as the centralized repository for all **Domain Models** used throughout the project. These are implemented using Pydantic v2 and ensure that the core business logic remains decoupled from the specific implementation details of the database (SQLAlchemy/SQLite) or the web layer (FastAPI).
+
+---
+
+## Model Hierarchy
+
+DECNET categorizes its models into two primary functional groups: **INI Specifications** and **Runtime Configurations**.
+
+### 1. INI Specifications (Input Validation)
+These models are designed to represent the structure of a `decnet.ini` file. They are primarily consumed by the `ini_loader.py` during the parsing of user-provided configuration files.
+
+- **`IniConfig`**: The root model for a full deployment specification. It includes global settings like `subnet`, `gateway`, and `interface`, and contains a list of `DeckySpec` objects.
+- **`DeckySpec`**: A high-level description of a machine. It contains optional fields that the user *may* provide in an INI file (e.g., `ip`, `archetype`, `services`).
+- **`CustomServiceSpec`**: Defines external "Bring-Your-Own" services using Docker images and custom execution commands.
+
+### 2. Runtime Configurations (Operational State)
+These models represent the **active, fully resolved state** of the deployment. Unlike the specifications, these models require all fields to be populated and valid.
+
+- **`DecnetConfig`**: The operational root of a deployment. It includes the resolved network settings and the list of active `DeckyConfig` objects. It is used by the **Engine** for orchestration and is persisted in `decnet-state.json`.
+- **`DeckyConfig`**: A fully materialized decoy configuration. It includes generated hostnames, resolved distro images, and specific IP addresses.
+
+---
+
+## The Fleet Transformer (`fleet.py`)
+
+The connection between the **Specifications** and the **Runtime Configurations** is handled by `decnet/fleet.py`.
+
+The function `build_deckies_from_ini` takes an `IniConfig` as input and performs the following "up-conversion" logic:
+- **IP Allocation**: Auto-allocates free IPs from the subnet for any deckies missing an explicit IP in the INI.
+- **Service Resolution**: Validates that all requested services exist in the registry and assigns defaults from archetypes if needed.
+- **Environment Inheritance**: Inherits settings like rotation intervals (`mutate_interval`) from the global INI context down to individual deckies.
+
+---
+
+## Structural Validation: `IniContent`
+
+To ensure that saved deployments in the database or provided by the API remain structurally sound, DECNET uses a specialized `IniContent` type.
+
+- **`validate_ini_string`**: A pre-validator that uses Python's native `configparser`. It ensures that the content is a valid INI string, does not exceed 512KB, and contains at least one section.
+- **Standardized Errors**: It raises specifically formatted `ValueError` exceptions that are captured by both the CLI and the Web UI to provide clear feedback to the user.
+
+---
+
+## Key Consumer Modules
+
+| Module | Usage |
+| :--- | :--- |
+| **`decnet/ini_loader.py`** | Uses `IniConfig` and `DeckySpec` to parse raw `.ini` files into structured objects. |
+| **`decnet/fleet.py`** | Transforms `IniConfig` specs into `DeckyConfig` operational models. |
+| **`decnet/config.py`** | Uses `DecnetConfig` and `DeckyConfig` to manage the lifecycle of `decnet-state.json`. |
+| **`decnet/web/db/models.py`** | Utilizes `IniContent` to enforce structural validity on INI strings stored in the database. |