# 🌿 Architektur-Dokumentation: Gartenprojekt (Symfony)

## 1. Vision & Kernprinzipien
Das Ziel dieser Architektur ist eine strikte Trennung zwischen technischer Infrastruktur, Geschäftslogik und den Liefermechanismen. Wir verfolgen einen Ansatz, der an **Clean Architecture** und **Hexagonal Architecture** angelehnt ist.

### Grundregeln:
*   **Unidirektionaler Fluss:** `UI` $\rightarrow$ `Logic` $\rightarrow$ `Data`. Ein Layer darf niemals Informationen aus einem übergeordneten Layer importieren.
*   **Dependency Inversion:** Die `Logic`-Schicht definiert die Anforderungen (Interfaces). Die `Data`-Schicht implementiert diese. Die Logik ist somit vollständig unabhängig von der Datenbank-Technologie oder externen APIs.
*   **Model-Zentrierung:** Das Model ist das Herzstück der Applikation. Es ist ein anämisches POPO (Plain Old PHP Object) und dient als primärer Datenträger zwischen den Schichten.
*   **Atomarität:** Business-Operationen sind atomar. Entweder alles wird gespeichert oder nichts (Transaction Management via `TransactionManagerInterface`).

---

## 2. Die Schichtenarchitektur

### 🟢 UI Layer (Delivery Mechanisms)
Die UI-Schicht ist die dünne Eintrittspforte. Sie besitzt keine Geschäftslogik.
*   **Einstiegspunkte:** `Http` (Controller), `Console` (Commands), `Queue` (MessageHandlers).
*   **Verantwortlichkeiten:**
    *   Mapping von Input auf **DTOs**.
    *   Syntaktische Validierung via Symfony Constraints am DTO.
    *   Grobe Autorisierungsprüfung (Rollen-basiert).
    *   Aufruf des entsprechenden **UseCase**.

### 🔵 Logic Layer (Business Core)
Hier wird definiert, *was* das System tut. Die Logik ist in Orchestrierung und zustandslose Fachlogik unterteilt.

#### A. Orchestrierung & State
*   **UseCase:** Der Dirigent eines Business-Prozesses. Er koordiniert: `Authorization` $\rightarrow$ `Validation` $\rightarrow$ `Calculation` $\rightarrow$ `Save`. Er steuert die Transaktionsgrenzen.
*   **Manager:** Zuständig für das **State Management**. Implementiert das *Cache-Aside Pattern* (Prüfung Cache vor Provider) und steuert die Invalidierung via Cache-Tags nach Schreibvorgängen.

#### B. Spezialisierte Logik (Stateless Services)
Zur Vermeidung von "Fat Managers" wird Fachlogik ausgelagert:
*   **Calculators:** Pure Functions für Berechnungen $\rightarrow$ gibt Werte zurück.
*   **Policies:** Business-Regelprüfungen $\rightarrow$ gibt `boolean` zurück.
*   **Validators:** Komplexe semantische Zustandsprüfungen $\rightarrow$ wirft `DomainException`.
*   **Strategies:** Kapselung austauschbarer Algorithmen.

#### C. Domain Objekte
*   **Models:** Primäre Datencontainer (z.B. `GardenPlan`). Anämisch und unabhängig von der DB.
*   **DTOs:** Transportobjekte zwischen UI und Logic.
*   **Domain Events:** Dünne Ereignisse, die manuell im UseCase nach erfolgreichem Commit getriggert werden.

### 🔴 Data Layer (Infrastructure)
Die technische Realisierung. Alles hier ist austauschbar, solange die Interfaces der Logic-Schicht erfüllt werden.
*   **Provider / Processor:** Implementierungen der Interfaces (`Provider` = Lesen | `Processor` = Schreiben).
*   **Entities:** Technische Repräsentationen für Doctrine (z.B. `GardenPlanEntity`).
*   **Mappers:** Explizite Klassen, die zwischen `Entity` $\leftrightarrow$ `Model` transformieren (KI-generiert/manuell).

---

## 3. Technischer Workflow & Pipeline

### Der Schreib-Pfad (Write Flow)
`UI` $\rightarrow$ `DTO` $\rightarrow$ `UseCase (Start Transaction)` $\rightarrow$ `Auth Check` $\rightarrow$ `Validator` $\rightarrow$ `Policy` $\rightarrow$ `Calculator` $\rightarrow$ `Manager` $\rightarrow$ `Processor` $\rightarrow$ `Mapper` $\rightarrow$ `Entity` $\rightarrow$ `DB` $\rightarrow$ `Commit` $\rightarrow$ `Trigger Events`.

### Der Lese-Pfad (Read Flow)
`UI` $\rightarrow$ `UseCase` $\rightarrow$ `Manager (Cache check)` $\rightarrow$ `Provider Interface` $\rightarrow$ `Implementation` $\rightarrow$ `Mapper` $\rightarrow$ `Model` $\rightarrow$ `UI`.

---

## 4. Querschnittsfunktionen

### Dependency Injection & Composition Root
Um eine strikte Entkopplung zu gewährleisten, wird die `Logic`-Schicht niemals direkt auf konkrete Implementierungen referenzieren (kein hartcodiertes `#[Autowire(service: ...)]`).
*   **Implicit Autowiring:** Bei einer einzigen Implementierung pro Interface nutzt Symfony das Standard-Autowiring.
*   **Composition Root:** Die `services.yaml` fungiert als zentrale Konfigurationsinstanz, in der Interfaces auf konkrete Implementierungen gemappt werden (Alias/Bind), um die Infrastruktur von außen steuerbar zu machen.

### Fehlermanagement & Exception-Handling
Ein zentrales System mappt fachliche Fehler auf HTTP-Standards:
*   **Hierarchie:** Alle Fachfehler erben von einer Basis-`DomainException`.
*   **Mapping:** Ein `Symfony ExceptionListener` fängt diese ab und mappt sie auf Statuscodes:
    *   `ResourceNotFoundException` $\rightarrow$ 404
    *   `AccessDeniedException` $\rightarrow$ 403
    *   `BusinessRuleViolationException` $\rightarrow$ 422/400
*   **Format:** Die Antwort erfolgt im **RFC 7807 (Problem Details for HTTP APIs)** Format, um dem Frontend präzise, maschinenlesbare Fehler zu liefern.

### Transaktionssteuerung & Asynchronität
*   **Transaction Management:** Abstrahiert über ein `TransactionManagerInterface`.
*   **Messenger:** Outbound-Nachrichten werden erst nach erfolgreichem DB-Commit versendet, um inkonsistente Benachrichtigungen ("Ghost Notifications") zu vermeiden.

---

## 5. Namensmusterkatalog

| Komponente | Muster | Beispiel |
| :--- | :--- | :--- |
| **Model** | `[Entity]` | `GardenPlan` |
| **Entity** | `[Entity]Entity` | `GardenPlanEntity` |
| **UseCase** | `[Action][Entity]UseCase` | `CreateGardenPlanUseCase` |
| **Manager** | `[Entity]Manager` | `GardenPlanManager` |
| **Calculator** | `[Topic]Calculator` | `SpacingCalculator` |
| **Policy** | `[Rule]Policy` | `CompatibilityPolicy` |
| **Validator** | `[Entity]Validator` | `GardenLayoutValidator` |
| **Provider Interface**| `[Entity]ProviderInterface` | `GardenPlanProviderInterface` |
| **Processor Interface**| `[Entity]ProcessorInterface`| `GardenPlanProcessorInterface`|
| **Mapper** | `[Src]To[Tgt]Mapper` | `GardenPlanEntityToModelMapper`|
| **DTO** | `[Action][Entity]Dto` | `UpdateGardenPlanDto` |

---

## 6. Ordnerstruktur (Hybrid-Feature Ansatz)

```text
src/
├── UI/
│   ├── Http/Controller/[Feature]/      # z.B. /Planning/GardenPlanController.php
│   ├── Console/Command/[Feature]/     # z.B. /Irrigation/StartWateringCommand.php
│   └── Queue/MessageHandler/[Feature]/ # z.B. /Notification/SendMailHandler.php
│
├── Logic/
│   ├── UseCase/[Feature]/              # z.B. /Planning/CreateGardenPlanUseCase.php
│   ├── Manager/[Feature]/              # z.B. /Planning/GardenPlanManager.php
│   ├── Domain/
│   │   ├── Model/[Feature]/            # z.B. /Planning/GardenPlan.php
│   │   ├── DTO/[Feature]/             # z.B. /Planning/UpdatePlanDto.php
│   │   └── Service/[Feature]/          # Calculator, Policy, Validator, Strategy
│   └── Interface/        # Provider & Processor Interfaces
│
├── Data/
│   ├── Doctrine/
│   │   ├── Entity/[Feature]/           # z.B. /Planning/GardenPlanEntity.php
│   │   └── Mapping/[Feature]/          # z.B. /Planning/GardenPlanMapper.php
│   └── Implementation/
│       ├── Provider/[Feature]/         # Realisierung der Interfaces
│       └── Processor/[Feature]/        # Realisierung der Interfaces
```