refactor(structure): reorganize monorepo with projects, terraform hierarchy, and strict k8s namespace rules

2026-10-12 13:49:41 +02:00
parent 4831147087
commit 8f01b75bd6
4766 changed files with 551 additions and 91 deletions
@@ -0,0 +1,74 @@
+# Shelly Fan Control Agent Documentation
+
+This directory manages the configuration, code templating, and deployment for the Shelly Plug S (Gen 3) that controls the cellar ventilation fan to prevent mold.
+
+## Domain Structure & Key Files
+
+*   **[main.tf](file:///Users/moritz/src/infrapuzzle/terraform/shelly/main.tf)**: Coordinates rendering the JavaScript template and executing the Python upload script.
+*   **[variables.tf](file:///Users/moritz/src/infrapuzzle/terraform/shelly/variables.tf)**: Defines MAC addresses for the Bluetooth sensors, safety parameters, and the mold calculation coefficients.
+*   **[scripts/Taupi-4.0.js](file:///Users/moritz/src/infrapuzzle/terraform/shelly/scripts/Taupi-4.0.js)**: The source Shelly control script containing the logic for parsing Bluetooth BTHome events, calculating dew points, evaluating mold danger, and switching the relay.
+*   **[scripts/Taupi-4.0.templated.js](file:///Users/moritz/src/infrapuzzle/terraform/shelly/scripts/Taupi-4.0.templated.js)**: The locally generated script rendering the variables passed from Terraform. Do not edit directly.
+*   **[scripts/upload.py](file:///Users/moritz/src/infrapuzzle/terraform/shelly/scripts/upload.py)**: Helper script executing during `terraform apply` to upload the templated script to the Shelly device over local HTTP RPC commands.
+
+## Architecture Decisions & Logic Gates
+
+The ventilation controller uses a **modular logic-gate architecture** designed to keep the cellar dry while preventing cellar overheating in summer and overcooling in winter.
+
+### 1. Decoupled Mold Alert (Sedlbauer LIM I)
+To distinguish between **routine/proactive drying** and **genuine mold risk**, the mold alert (`taupi_is_critical` metric $\rightarrow$ Prometheus alert `TaupiFanMoldDanger`) is decoupled from the fan start threshold:
+*   **LIM I Baseline**: $RH_{crit}(T) = 80\% - 0.5 \cdot (T - 10)$
+*   **Alert Activation**: $RH_{in} \ge RH_{crit}(T) - \text{critical\_humi\_buffer}$
+*   **Behavior**: Fires an alert only when humidity poses an actual germination hazard on cold outer walls.
+
+### 2. Cellar Overheating Prevention
+In warm months, blowing outdoor air into a cool cellar can heat up the cellar mass.
+*   **Ceiling Protection**: If $T_{in} \ge 20^\circ\text{C}$, the fan is **only** permitted to run if outdoor air is cooler than inside ($T_{out} \le T_{in}$).
+*   **Warming Allowance**: If $T_{in} < 20^\circ\text{C}$, gentle warming is permitted, but outdoor temperature cannot exceed $20^\circ\text{C}$ ($T_{out} \le 20^\circ\text{C}$).
+
+### 3. Seasonal Target Humidities
+*   **Cold / Winter Mode** ($T_{in} < 14^\circ\text{C}$ or $T_{out} < 10^\circ\text{C}$): Targets **50% RH**. Once 50% RH is reached, the fan stops to preserve cellar warmth.
+*   **Warm / Summer Mode**: Targets **40% RH** for maximum drying.
+*   **Hard Cold Floor**: The fan is blocked if $T_{in} \le \text{mindesttemperatur}$ (default 10°C).
+
+### 4. 2-Tier Scheduling & Optimal Night Window
+In Central Europe / Germany, the diurnal temperature and absolute humidity minimum occurs in early morning (~03:00–07:00, peak around 05:00):
+*   **Urgent Drying ($RH_{in} > 60\%$)**: Runs 24/7 whenever psychrometric and temperature guards allow.
+*   **Routine Drying ($40\% \le RH_{in} \le 60\%$)**: Restricted to the **optimal night window (03:00–07:00)** to exploit maximum dew point spread.
+
+### 5. Duty Cycle & Thermal Equilibrium
+To allow cellar air and thermal wall mass to equilibrate and prevent non-stop continuous blowing:
+*   **Max Continuous Runtime**: 90 minutes.
+*   **Cooldown Rest**: 45 minutes pause after hitting max continuous runtime.
+
+---
+
+## Logic Gate Summary
+
+```
+                      [ Telemetry Fresh & Valid? ]
+                                   │ YES
+                      [ Cooldown Rest Elapsed? ]
+                                   │ YES
+                      [ Cellar Temp > Min Floor (10°C)? ]
+                                   │ YES
+                      [ Overheating Safe (Tout vs Tin)? ]
+                                   │ YES
+                      [ Cellar RH > Target (40% / 50%)? ]
+                                   │ YES
+                      [ Dew Point Spread > Threshold (2°C)? ]
+                                   │ YES
+                      [ Urgent (>60%) OR Night Window (03-07)? ]
+                                   │ YES
+                          ┌────────┴────────┐
+                          ▼                 ▼
+                   [ START BLOWER ]   [ LOG REASON ]
+```
+
+---
+
+## Sources & References
+
+*   **[BoeserBob/Taupi-4.0](https://github.com/BoeserBob/Taupi-4.0)**: The original upstream Shelly dew point ventilation controller repository.
+*   **[Klaus Sedlbauer Biography (Wikipedia)](https://de.wikipedia.org/wiki/Klaus_Sedlbauer)**: The researcher who developed the Lowest Isopleth for Mould (LIM) curves at Fraunhofer IBP.
+*   **[WUFI Biohygrothermal Model](https://wufi.de/en/wufi-software/wufi-bio/)**: Fraunhofer IBP documentation explaining dynamic mold growth and spore germination models.
+