initiales Projektsetup als skeleton für fresh flask + architecture

docs/coding-standards.md

@@ -0,0 +1,86 @@
+# Coding Standards & Header-Spezifikation
+
+Dieses Dokument definiert die Richtlinien für Dateiköpfe, Dokumentation und Code-Kommentare im Projekt **Formeleon**. Alle von KI-Agenten oder Entwicklern erstellten Quelltexte müssen diesen Vorgaben entsprechen.
+
+---
+
+## 1. Autor & Metadaten
+
+* **Autor:** Björn Runden (`br@runden.net`)
+* **Sprache im Code:** Englisch (Variablen, Funktionen, Modulnamen, Code-Kommentare).
+* **Sprache der Dokumentation:** Deutsch.
+
+---
+
+## 2. Python Dateiköpfe & PyDoc Standards
+
+### 2.1 Datei-Header (`.py`)
+Jede Python-Datei beginnt mit folgendem Header:
+
+```python
+# ==============================================================================
+# Formeleon - Multi-tenant Form Generator
+# Author: Björn Runden <br@runden.net>
+# Module: <Modulname / Pfad>
+# Description: <Kurze Beschreibung des Moduls>
+# ==============================================================================
+```
+
+### 2.2 PyDoc für Funktionen, Methoden & Klassen
+Jede Klasse, Funktion und Methode **MUSS** über einen PyDoc-Docstring dokumentiert sein:
+
+```python
+def validate_handshake_token(public_key: str, origin: str) -> bool:
+    """
+    Validates the client handshake request against the tenant registry.
+
+    :param public_key: Public API key transmitted by the client snippet.
+    :param origin: Origin/Referer header provided by the client request.
+    :return: True if the request origin matches allowed domains for the tenant, False otherwise.
+    """
+    pass
+```
+
+---
+
+## 3. Jinja2 & HTML Standards (`.j2`, `.html`)
+
+### 3.1 Datei-Header
+Jedes Jinja2-Template oder HTML-File beginnt mit einem Kommentar-Header:
+
+```html
+{# ==============================================================================
+   Formeleon - Multi-tenant Form Generator
+   Author: Björn Runden <br@runden.net>
+   Template: <Template Name>
+   Description: <Zweck des Templates>
+   ============================================================================== #}
+```
+
+### 3.2 Dokumentation von Jinja2-Logik
+Einfache Variablenersetzungen (`{{ user.name }}`) benötigen keinen Kommentar. Logikführende Blöcke (Schleifen, Modale, Bedingungen, Makros) **MÜSSEN** dokumentiert werden:
+
+```html
+{# Iterates over active form fields and renders the corresponding input control #}
+{% for field in form_fields %}
+    <div class="mb-3">
+        {# Render dynamic field label #}
+        <label for="{{ field.id }}" class="form-label">{{ field.label }}</label>
+        <input type="{{ field.type }}" id="{{ field.id }}" name="{{ field.name }}" class="form-control">
+    </div>
+{% endfor %}
+```
+
+---
+
+## 4. JavaScript / CSS Standards (`.js`, `.css`)
+
+### 4.1 Datei-Header
+```javascript
+/==============================================================================
+ * Formeleon - Multi-tenant Form Generator
+ * Author: Björn Runden <br@runden.net>
+ * Script: <Script Name>
+ * Description: <Zweck des Scripts>
+ *============================================================================*/
+```