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>
+ *============================================================================*/
+```

docs/deployment.md

@@ -0,0 +1,34 @@
+# Deployment & CI/CD Guide
+
+## 1. Gitea Actions Workflow
+
+Bei einem Push auf den `main`-Branch oder einem Release-Tag führt der Gitea-Runner automatisiert folgende Schritte auf dem Zielserver aus:
+
+1. Code-Update via `git pull`.
+2. Erstellen/Aktualisieren der Docker-Images.
+3. Zero-Downtime Restart der Container via Docker Compose.
+
+---
+
+## 2. Docker Setup
+
+Das System läuft in einem schlanken Gunicorn-Container hinter einem Reverse Proxy.
+
+### `docker-compose.yml` (Auszug)
+```yaml
+version: '3.8'
+
+services:
+  web:
+    build: .
+    restart: always
+    env_file:
+      - .env
+    ports:
+      - "8000:8000"
+    volumes:
+      - sqlite_data:/app/data
+
+volumes:
+  sqlite_data:
+```

docs/dev-guide.md

@@ -0,0 +1,30 @@
+# Developer Guide & Local Emulation
+
+## 1. Local Auth Bypass (Zitadel-Dummy)
+
+Für die lokale Entwicklung auf `127.0.0.1` oder benutzerdefinierten Dev-Domains kann die OIDC-Authentifizierung umgangen werden.
+
+In der `.env`:
+```env
+DEV_MODE=true
+DEV_USER_ROLE=admin
+DEV_TENANT_ID=tenant_dev_123
+```
+
+Ist `DEV_MODE=true` gesetzt, injiziert die Middleware automatisch eine Mock-Session für den angegebenen Dev-User, ohne Redirects zu Zitadel auszuführen.
+
+---
+
+## 2. reCAPTCHA v3 Mocking
+
+Im Dev-Modus wird die Google reCAPTCHA API nicht kontaktiert.
+
+* **Erfolg-Simulation:** Standardmäßig gibt der Mock-Service einen Score von `0.9` zurück.
+* **Fehlschlag-Simulation:** Durch Setzen von `MOCK_RECAPTCHA_SCORE=0.1` in der `.env` kann das Abweisen von Spam-Submissions lokal getestet werden.
+
+---
+
+## 3. CLI Commands & Maintenance
+
+* **Datenbank-Seeding:** `flask seed-db` (Erstellt Test-Mandanten und Beispiel-Formulare).
+* **E-Mail Dump Trigger:** `flask run-scheduled-export --tenant-id=<ID> --period=daily` (Führt datenbank-agnostischen Export via SQLAlchemy aus und versendet die Mail).