Improve docs with history and ai instructions

AGENTS.md

@@ -12,6 +12,8 @@ This file provides guidance to agents when working with code in this repository.
 ## Verification Execution
 - Das Hauptprogramm für Verifizierungen sollte wie folgt gestartet werden:
   `python3 main.py --timeout 1`
+  oder um eine längere Laufzeit zu analysieren:
+  `python3 main.py --timeout 30`
 
 ## Mandatory Documentation and Test Maintenance
 
@@ -46,4 +48,199 @@ Diese Richtlinie gilt für alle AI-Agenten, die Code oder Systemkonfigurationen
 - [ ] Gesamte Testsuite (`pytest`) ohne Fehler durchgelaufen
 - [ ] Änderungen mit den Projekt‑Konventionen konsistent
 
-Diese Richtlinie gewährleistet, dass Code‑Änderungen nicht isoliert, sondern im Kontext des gesamten Projekts betrachtet werden und die langfristige Wartbarkeit sowie die Zuverlässigkeit der Software erhalten bleibt.
+Diese Richtlinie gewährleistet, dass Code‑Änderungen nicht isoliert, sondern im Kontext des gesamten Projekts betrachtet werden und die langfristige Wartbarkeit sowie die Zuverlässigkeit der Software erhalten bleibt.
+
+## Architecture-First Development Process
+
+Dieser Abschnitt definiert den verbindlichen Arbeitsablauf für die Entwicklung neuer Funktionen im PySignalduino-Projekt. Der zentrale Grundsatz lautet: **Jede neue Funktion beginnt mit einer vorausschauenden Erweiterung der Architekturdokumentation.** Diese dokumentierte Architektur dient als die einzige verbindliche Spezifikation und der primäre Leitfaden für alle nachfolgenden Implementierungsschritte.
+
+### Grundprinzipien
+
+1. **Architektur vor Code:** Design-Entscheidungen müssen zuerst in der Dokumentation reflektiert und abgestimmt werden, bevor jeglicher Code geschrieben wird.
+2. **Dokumentation als Single Source of Truth:** Die Architekturdokumentation ist die autoritative Referenz für alle Implementierungsentscheidungen.
+3. **Traceability:** Jede Code-Änderung muss auf eine spezifische Architekturentscheidung zurückführbar sein.
+4. **Compliance-Checks:** Implementierungen müssen regelmäßig auf Konformität mit der dokumentierten Architektur überprüft werden.
+
+### Vier-Phasen-Prozess
+
+#### Phase 1: Architekturdefinition mit verbindlichem Architekturproposal
+- **Ziel:** Erstellung eines vollständigen Architekturproposals, das alle Design-Entscheidungen dokumentiert
+- **Aktivitäten:**
+  - Anforderungsanalyse und Scope-Definition
+  - Erstellung von Architekturdiagrammen (Mermaid, PlantUML)
+  - Definition von Schnittstellen und Datenmodellen
+  - Risikoanalyse und Alternativenbewertung
+  - Erstellung eines Architecture Decision Record (ADR)
+- **Deliverables:**
+  - Architekturproposal im AsciiDoc-Format
+  - Mermaid-Diagramme für Komponenten- und Sequenzabläufe
+  - ADR im `docs/architecture/decisions/` Verzeichnis
+  - Review-Protokoll mit Genehmigung durch Architecture Owner
+
+#### Phase 2: Implementierungsplanung basierend auf genehmigter Architektur
+- **Ziel:** Detaillierte Planung der Implementierungsschritte unter strikter Einhaltung der Architektur
+- **Aktivitäten:**
+  - Aufteilung in konkrete Arbeitspakete (Tasks)
+  - Definition von Akzeptanzkriterien für jede Komponente
+  - Planung von Teststrategien (Unit, Integration, System)
+  - Ressourcen- und Zeitplanung
+  - Erstellung von Mockups/Prototypen für kritische Pfade
+- **Deliverables:**
+  - Implementierungsplan mit Task-Breakdown
+  - Testplan mit Coverage-Zielen
+  - Prototypen für Risikokomponenten
+  - Genehmigung durch Feature Developer und Reviewer
+
+#### Phase 3: Implementierung mit strikter Konformität zur Architektur
+- **Ziel:** Code-Entwicklung unter ständiger Referenzierung der Architekturdokumentation
+- **Aktivitäten:**
+  - Iterative Entwicklung gemäß Implementierungsplan
+  - Regelmäßige Architektur-Compliance-Checks
+  - Dokumentation von Abweichungen und deren Begründung
+  - Kontinuierliche Integration und Code-Reviews
+  - Anpassung der Dokumentation bei notwendigen Änderungen
+- **Deliverables:**
+  - Vollständiger implementierter Code
+  - Aktualisierte Dokumentation (Inline-Kommentare, Docstrings)
+  - Testsuite mit ausreichender Coverage
+  - Compliance-Report gegenüber Architekturproposal
+
+#### Phase 4: Validation & Integration mit Architektur-Compliance-Checks
+- **Ziel:** Validierung der Implementierung gegen Architekturanforderungen und Integration in das Gesamtsystem
+- **Aktivitäten:**
+  - Ausführung aller Tests (Unit, Integration, System)
+  - Architektur-Compliance-Review durch Architecture Owner
+  - Performance- und Sicherheitsaudits
+  - Integrationstests mit bestehenden Komponenten
+  - Endgültige Dokumentationsprüfung
+- **Deliverables:**
+  - Testberichte und Coverage-Report
+  - Compliance-Zertifizierung durch Architecture Owner
+  - Finalisierte Dokumentation
+  - Merge-Request mit vollständiger Nachweisbarkeit
+
+### Rollen und Verantwortlichkeiten
+
+#### Architecture Owner
+- **Verantwortlichkeiten:**
+  - Genehmigung von Architekturproposals
+  - Durchführung von Architektur-Reviews
+  - Compliance-Checks während der Implementierung
+  - Finale Freigabe für Integration
+- **Befugnisse:**
+  - Veto-Recht bei Architekturverstößen
+  - Anforderung von Design-Änderungen
+  - Genehmigung von ADRs
+
+#### Feature Developer
+- **Verantwortlichkeiten:**
+  - Erstellung von Architekturproposals
+  - Implementierung gemäß genehmigter Architektur
+  - Dokumentation von Design-Entscheidungen
+  - Durchführung von Selbst-Checks auf Compliance
+- **Befugnisse:**
+  - Vorschlag von Architekturalternativen
+  - Beantragung von Architektur-Änderungen via ADR
+  - Code-Reviews für Teammitglieder
+
+#### Reviewer
+- **Verantwortlichkeiten:**
+  - Code-Review mit Fokus auf Architekturkonformität
+  - Prüfung der Testabdeckung
+  - Validierung der Dokumentationsaktualität
+  - Sicherstellung der Wartbarkeit
+- **Befugnisse:**
+  - Blockierung von Merge-Requests bei Compliance-Problemen
+  - Anforderung zusätzlicher Tests
+  - Empfehlung für Architecture Owner
+
+### Architecture Documentation Standards
+
+#### AsciiDoc-Templates
+Alle Architekturdokumente müssen den standardisierten Templates folgen:
+- **Architekturproposal:** `docs/architecture/templates/proposal_template.adoc`
+- **ADR (Architecture Decision Record):** `docs/architecture/templates/adr_template.adoc`
+- **Komponentenbeschreibung:** `docs/architecture/templates/component_template.adoc`
+
+#### Mermaid-Diagramme
+- **Verpflichtende Diagrammtypen:**
+  - Komponentendiagramm (Component Diagram)
+  - Sequenzdiagramm (Sequence Diagram)
+  - Zustandsdiagramm (State Diagram) bei komplexen Zustandsmaschinen
+- **Einbettung:** Direkte Einbettung in AsciiDoc-Dokumente via `[mermaid]`-Block
+- **Versionierung:** Diagramme müssen im `docs/architecture/diagrams/` Verzeichnis als `.mmd`-Dateien gespeichert werden
+
+#### ADRs (Architecture Decision Records)
+- **Format:** Lightweight ADR gemäß MADR-Standard
+- **Speicherort:** `docs/architecture/decisions/`
+- **Nummerierung:** Sequentiell (ADR-001, ADR-002, ...)
+- **Inhalt:** Kontext, Entscheidung, Konsequenzen, Alternativen
+
+### Erweiterte Checkliste vor dem Commit
+
+Diese Checkliste erweitert die bestehende Checkliste um Architektur-spezifische Prüfpunkte:
+
+#### Architektur-Compliance
+- [ ] Architekturproposal liegt vor und ist genehmigt
+- [ ] ADR für alle wesentlichen Design-Entscheidungen erstellt
+- [ ] Implementierung folgt den spezifizierten Schnittstellen
+- [ ] Keine Verletzung von Architekturprinzipien (z.B. Single Responsibility)
+- [ ] Datenmodelle entsprechen den definierten Schemata
+
+#### Dokumentation
+- [ ] Architekturdokumentation aktualisiert (AsciiDoc-Dateien)
+- [ ] Mermaid-Diagramme auf Aktualität geprüft
+- [ ] Inline-Kommentare und Docstrings angepasst
+- [ ] API-Referenzen konsistent mit Implementierung
+- [ ] README.md und andere Markdown-Dateien geprüft
+
+#### Tests
+- [ ] Bestehende Tests angepasst und erfolgreich ausgeführt
+- [ ] Neue Tests für geänderte/neue Logik erstellt
+- [ ] Architektur-spezifische Integrationstests vorhanden
+- [ ] Test-Coverage mindestens 80% für neue Komponenten
+- [ ] Gesamte Testsuite (`pytest`) ohne Fehler durchgelaufen
+
+#### Code-Qualität
+- [ ] Code-Review durch Reviewer durchgeführt
+- [ ] Architektur-Compliance-Check durch Architecture Owner
+- [ ] Linting (`ruff`, `black`) ohne Fehler
+- [ ] Type-Checks (`mypy`) erfolgreich
+- [ ] Änderungen mit den Projekt-Konventionen konsistent
+
+### Prozessvisualisierung
+
+```mermaid
+flowchart TD
+    A[Neue Funktionsanforderung] --> B[Phase 1: Architekturdefinition]
+    B --> C{Architekturproposal<br/>genehmigt?}
+    C -->|Ja| D[Phase 2: Implementierungsplanung]
+    C -->|Nein| B
+    D --> E[Phase 3: Implementierung]
+    E --> F[Regelmäßige Compliance-Checks]
+    F --> G{Compliance<br/>verletzt?}
+    G -->|Ja| H[ADR für Änderung<br/>oder Rückführung]
+    H --> E
+    G -->|Nein| I[Phase 4: Validation & Integration]
+    I --> J{Alle Tests bestanden<br/>und Compliance ok?}
+    J -->|Ja| K[Merge & Deployment]
+    J -->|Nein| I
+
+    subgraph "Architektur-Governance"
+        L[Architecture Owner Review]
+        M[ADR Management]
+        N[Compliance Monitoring]
+    end
+
+    B --> L
+    D --> L
+    I --> L
+    H --> M
+    F --> N
+```
+
+### Verbindlichkeit
+
+Dieser Architecture-First Development Process ist für **alle** neuen Funktionen und wesentlichen Änderungen verbindlich. Ausnahmen sind nur bei kritischen Bugfixes erlaubt und müssen durch einen Emergency-ADR dokumentiert werden. Jede Abweichung vom Prozess muss vom Architecture Owner genehmigt werden.
+
+Die Einhaltung dieses Prozesses gewährleistet, dass Design-Entscheidungen bewusst getroffen, dokumentiert und nachvollziehbar sind, was die langfristige Wartbarkeit, Skalierbarkeit und Qualität des PySignalduino-Projekts sicherstellt.

README.md

@@ -2,6 +2,49 @@
 
 Dieses Projekt ist eine moderne Python-Implementierung der SIGNALDuino-Protokolle mit vollständiger **asyncio**-Unterstützung und integrierter **MQTT-Bridge**. Es ermöglicht die Kommunikation mit SIGNALDuino-Hardware (über serielle Schnittstelle oder TCP) und veröffentlicht empfangene Signale sowie empfängt Steuerbefehle über MQTT.
 
+## Projektgeschichte
+
+PySignalduino ist Teil des **RFD-FHEM**-Ökosystems, das ursprünglich als Perl-basierte Lösung für die Hausautomationssoftware FHEM begann. Die Entwicklung lässt sich in folgende Meilensteine unterteilen:
+
+### Ursprung: RFD-FHEM und SIGNALDuino
+- **2010er Jahre**: Die RFD-FHEM-Community entwickelte Hardware- und Softwarelösungen für die Funkkommunikation mit 433/868 MHz Geräten.
+- **SIGNALDuino-Hardware**: Ein Arduino-basierter Transceiver mit CC1101 Funkmodul, der als kostengünstige Alternative zu kommerziellen Lösungen entstand.
+- **Perl-Implementierung**: Die ursprüngliche Protokollimplementierung erfolgte in Perl als FHEM-Modul `00_SIGNALduino.pm`.
+
+### Migration zu Python
+- **2020er Jahre**: Mit der wachsenden Popularität von Python und MQTT entstand der Bedarf nach einer moderneren, asynchronen Lösung.
+- **PySignalduino**: Diese Bibliothek portiert die Perl-Protokolle (`SD_Protocols.pm`, `SD_ProtocolData.pm`) in eine native Python-Implementierung.
+- **Asynchrone Architektur**: Vollständige `asyncio`-Integration für bessere Performance und einfachere Integration in moderne IoT-Systeme.
+
+### Community-Entwicklung
+- **Open Source**: Das Projekt wird von einer aktiven Community auf GitHub gepflegt und weiterentwickelt.
+- **Firmware-Entwicklung**: Die SIGNALDuino-Firmware wird parallel im Repository [RFD-FHEM/SIGNALDuino](https://github.com/RFD-FHEM/SIGNALDuino) entwickelt.
+- **Version 3.5.0**: Die aktuelle Firmware-Version bietet erweiterte Funktionen wie WiFi-Unterstützung für ESP32-basierte Boards.
+
+### Entwicklungsstatus
+
+> **⚠️ Entwicklungsstatus**
+>
+> PySignalduino befindet sich noch in aktiver Entwicklung und hat noch kein offizielles Release veröffentlicht. Die API kann sich zwischen Versionen ändern. Entwickler sollten bei der Verwendung Vorsicht walten lassen und auf mögliche Breaking Changes vorbereitet sein.
+
+### PySignalduino vs. Original
+PySignalduino ist keine direkte Portierung, sondern eine Neuimplementierung mit folgenden Unterschieden:
+- **Asynchrone Verarbeitung**: Statt Threads wird `asyncio` verwendet.
+- **MQTT-Integration**: Eingebaute MQTT-Bridge für nahtlose Integration in IoT-Ökosysteme.
+- **Moderne Python-Praktiken**: Typisierung, strukturierte Logging, Konfiguration über Umgebungsvariablen.
+
+## Controller-Code und Firmware
+
+Die SIGNALDuino-Firmware (Microcontroller-Code) wird in einem separaten Repository entwickelt:
+
+- **GitHub Repository**: https://github.com/RFD-FHEM/SIGNALDuino
+- **Aktuelle Version**: v3.5.0
+- **Unterstützte Hardware**:
+  - Arduino Nano mit CC1101
+  - ESP32-basierte Boards (z.B. ESP32-DevKitC)
+  - Maple Mini (STM32)
+- **Build-Anleitungen**: Das Repository enthält PlatformIO-Konfigurationen und Arduino-IDE-Projektdateien für einfache Kompilierung.
+
 ## Hauptmerkmale
 
 *   **Vollständig asynchron** – Basierend auf `asyncio` für hohe Performance und einfache Integration in asynchrone Anwendungen.

docs/01_user_guide/index.adoc

@@ -3,5 +3,80 @@
 
 Der Benutzer-Leitfaden enthält Anweisungen zur Installation, Konfiguration und grundlegenden Verwendung von PySignalduino.
 
+== Was ist PySignalduino?
+
+PySignalduino ist eine moderne Python-Bibliothek zur Kommunikation mit **SIGNALDuino**-Hardware – einem Arduino-basierten Transceiver für 433/868 MHz Funkkommunikation. Die Bibliothek bietet:
+
+* **Asynchrone Verarbeitung**: Vollständige `asyncio`-Integration für nicht-blockierende Operationen.
+* **MQTT-Bridge**: Eingebaute MQTT-Unterstützung für nahtlose Integration in Smart-Home-Systeme.
+* **Protokollbibliothek**: Portierung der originalen FHEM‑SIGNALDuino‑Protokolle (`SD_Protocols.pm`, `SD_ProtocolData.pm`) in Python.
+* **Moderne Transporte**: Unterstützung für serielle und TCP-Verbindungen.
+
+=== Unterschied zum Original
+PySignalduino ist keine direkte Portierung des Perl‑FHEM‑Moduls, sondern eine Neuimplementierung mit folgenden Schwerpunkten:
+
+* **Asynchrone Architektur**: Statt Threads wird `asyncio` verwendet, was bessere Skalierbarkeit und einfachere Integration in asynchrone Anwendungen ermöglicht.
+* **Typisierung**: Vollständige Typ‑Annotations für bessere Code‑Qualität und IDE‑Unterstützung.
+* **Konfiguration über Umgebungsvariablen**: Einfache Einrichtung ohne Codeänderungen.
+* **Umfangreiche Testsuite**: Hohe Testabdeckung zur Gewährleistung der Stabilität.
+
+=== Entwicklungsstatus
+
+[WARNING]
+====
+**Entwicklungsstatus**
+
+PySignalduino befindet sich noch in aktiver Entwicklung und hat noch kein offizielles Release veröffentlicht. Die API kann sich zwischen Versionen ändern. Entwickler sollten bei der Verwendung Vorsicht walten lassen und auf mögliche Breaking Changes vorbereitet sein.
+====
+
+=== Zielgruppe
+PySignalduino richtet sich an:
+
+* **Entwickler**, die SIGNALDuino‑Hardware in Python‑Projekte integrieren möchten.
+* **Smart‑Home‑Enthusiasten**, die eine MQTT‑Bridge für ihre Funkgeräte benötigen.
+* **Integratoren**, die bestehende FHEM‑Installationen um moderne Python‑Komponenten erweitern wollen.
+
+== Architektur-Übersicht
+
+PySignalduino folgt einer modular aufgebauten Architektur:
+
+[source,plantuml]
+----
+include::../../docs/diagrams/architecture.puml[]
+----
+
+Die Hauptkomponenten sind:
+
+1. **Transport Layer** (`signalduino.transport`):
+   * `SerialTransport` – Asynchrone serielle Kommunikation über `pyserial-asyncio`.
+   * `TcpTransport` – TCP‑Socket‑Verbindung.
+
+2. **Parser Layer** (`signalduino.parser`):
+   * `MCParser`, `MNParser`, `MSParser`, `MUParser` – Verarbeitung der verschiedenen SIGNALDuino‑Nachrichtentypen.
+
+3. **Protokollbibliothek** (`sd_protocols`):
+   * `SDProtocols` – Hauptklasse für Protokollerkennung und ‑dekodierung.
+   * `SDProtocolData` – Datenstrukturen für Protokolldefinitionen.
+
+4. **Controller** (`signalduino.controller`):
+   * `SignalduinoController` – Zentrale Steuerungsklasse, koordiniert Transport, Parser und MQTT.
+
+5. **MQTT‑Integration** (`signalduino.mqtt`):
+   * `MqttPublisher` – Asynchroner MQTT‑Client für Publikation und Subscription.
+
+6. **Befehls‑API** (`signalduino.commands`):
+   * `SignalduinoCommands` – Umfassende Schnittstelle zur Steuerung der SIGNALDuino‑Firmware.
+
+== Schnellstart
+
+Für einen schnellen Einstieg folgen Sie diesen Schritten:
+
+1. **Installation**: Siehe link:installation.adoc[Installationsanleitung].
+2. **Konfiguration**: Setzen Sie die erforderlichen Umgebungsvariablen (z.B. `SIGNALDUINO_SERIAL_PORT`, `MQTT_HOST`).
+3. **Programm starten**: Führen Sie `python3 main.py` aus.
+4. **MQTT‑Nachrichten überwachen**: Abonnieren Sie das Topic `signalduino/messages`, um dekodierte Signale zu empfangen.
+
+Ausführliche Anleitungen finden Sie in den folgenden Kapiteln.
+
 include::installation.adoc[]
 include::usage.adoc[]

docs/01_user_guide/installation.adoc

@@ -1,5 +1,10 @@
 = Installation
 
+[NOTE]
+====
+PySignalduino ist noch in Entwicklung. Es gibt bisher keine stabile Version – nutzen Sie die Software mit entsprechender Vorsicht.
+====
+
 == Voraussetzungen
 
 * Python 3.8 oder höher

docs/01_user_guide/usage.adoc

@@ -210,6 +210,8 @@ Die Log-Ausgabe zeigt den Status von Transport, Parser und MQTT.
 
 === Bekannte Probleme und Workarounds
 
+* **Entwicklungsstatus**: Da PySignalduino noch in aktiver Entwicklung ist, können sich Verhalten und API zwischen Commits ändern. Bei unerwartetem Verhalten prüfen Sie bitte die aktuelle Codebasis und melden Sie Issues auf GitHub.
+
 * **`aiomqtt`-Versionen:** Verwenden Sie `aiomqtt>=2.0.0`. Ältere Versionen können Inkompatibilitäten aufweisen.
 * **Windows und asyncio:** Unter Windows kann es bei seriellen Verbindungen zu Problemen mit asyncio kommen. Verwenden Sie `asyncio.ProactorEventLoop` oder weichen Sie auf TCP-Transport aus.
 * **Memory Leaks:** Bei langem Betrieb können asyncio-Tasks Speicher verbrauchen. Stellen Sie sicher, dass abgeschlossene Tasks garbage-collected werden. Verwenden Sie `asyncio.create_task` mit Referenzen, um Tasks später abbrechen zu können.

docs/02_developer_guide/contribution.adoc

@@ -1,5 +1,10 @@
 = Beitrag leisten (Contributing)
 
+[NOTE]
+====
+Da PySignalduino noch in aktiver Entwicklung ist, können sich Code-Strukturen und APIs schnell ändern. Bitte synchronisieren Sie Ihren Fork regelmäßig mit dem upstream-Repository.
+====
+
 Beiträge zum Projekt sind willkommen!
 
 == Workflow