formeleon/README.md

Formeleon 🦎

Mandantenfähiger, hochflexibler Formular-Generator mit nahtloser Website-Integration und integriertem Bot-Schutz.

Read this in English: README.EN.md

---

📋 Überblick

Formeleon ist ein zentral gehosteter Service (ChamäleonCloud), der es Webseitenbetreibern (Mandanten) ermöglicht, dynamische Formulare ohne Backend-Aufwand per HTML/JavaScript-Snippet in bestehende Webseiten einzubetten.

Kern-Features

• Nahtlose Integration: Einbettung via JS-Snippet ("Chamäleon-Effekt").
• Maximale Feldvariabilität: Dynamische JSON-Payloads via SQLite/SQLAlchemy.
• Integrierte Sicherheit: OIDC-Integration (Zitadel), Public-Key Handshake, Origin/Referer-Validierung & reCAPTCHA v3 Support.
• UX & Bot-Protection: Integriertes Ampel-System (Laderad/Clearance) für Absende-Buttons.
• Reporting & Export: Daten-Exports (CSV/JSON/YAML) per Stream oder automatisierte E-Mail-Dumps.

---

🛠️ Tech-Stack

• Backend: Python 3.13, Flask (Blueprint-Architektur), Flask-SQLAlchemy, Flask-Migrate (Alembic)
• Frontend (Admin-Panel): Bootstrap 5, Mithril.js / HTML5
• Authentication: OIDC via Zitadel (Admin-Panel)
• Deployment: Docker, Gunicorn, Gitea Actions (Runner)

---

🚀 Schnellstart (Lokal / Docker-less)

Das Projekt kann auf Windows/Linux komplett ohne Docker in einer Virtual Environment entwickelt werden:

1. Repository klonen & Umgebung einrichten:

   python -m venv venv
   
   # Auf Linux/Mac:
   source venv/bin/activate
   # Auf Windows:
   venv\Scripts\activate
   
   pip install -r requirements.txt
   

2. Umgebungsvariablen (optional): (Formeleon startet standardmäßig im Dev-Mode mit einer lokalen SQLite-DB formeleon.db)

3. Datenbank initialisieren & starten:

   # Migration-Repository initialisieren (nur einmalig!)
   flask db init
   
   # Datenbank-Schema erstellen
   flask db upgrade
   
   # Optionales Seeding mit Testdaten
   flask seed-db
   
   # Anwendung starten (auf Port 5000 mit Hot-Reload)
   flask run --port=5000 --debug
   

---

🐳 Schnellstart (Docker)

Für das vollständige Linux- / Staging-Gefühl kannst du Docker nutzen. Durch Volume-Mounts bleibt der Code synchron, und du kannst im Editor (Windows/Mac) programmieren.

# 1. Image bauen und Container starten
docker compose up --build

# 2. Anwendung beenden
# (Strg+C oder:)
docker compose down

# 3. Datenbank und Volumes komplett zurücksetzen
docker compose down -v && docker-compose up --build

Docker CLI-Kommandos ausführen

Du kannst flask Kommandos direkt gegen den laufenden Container feuern:

# Datenbank Migrationen anlegen
docker compose run --rm app flask db migrate -m "neue migration"

# Datenbank-Schema updaten
docker compose run --rm app flask db upgrade

# Datenbank mit Testdaten füllen
docker compose run --rm app flask seed-db

# Shell im Container öffnen
docker compose run --rm app bash

Zugriff auf die Anwendung

• Admin Dashboard: http://localhost:5000/admin/
• API Endpunkt: http://localhost:5000/api/v1/
• Health Check: http://localhost:5000/

---

🌍 Mehrsprachigkeit (i18n) via Flask-Babel

Das Admin-Dashboard von Formeleon unterstützt Mehrsprachigkeit (aktuell Deutsch und Englisch). Wir nutzen dafür den Standard Flask-Babel (gettext).

1. Texte im Code markieren

Damit das System erkennt, dass ein Text übersetzt werden soll, muss er im Python- oder HTML-Code mit der Funktion _() umschlossen werden.

In HTML (Jinja2 Templates):

<!-- Vorher -->
<h1>Welcome to the Dashboard</h1>

<!-- Nachher -->
<h1>{{ _('Welcome to the Dashboard') }}</h1>

In Python-Dateien:

from flask_babel import _

# Vorher
flash('Form saved successfully!', 'success')

# Nachher
flash(_('Form saved successfully!'), 'success')

2. Der Übersetzungs-Workflow (CLI)

Wenn neue Texte im Code markiert wurden, müssen diese extrahiert und die Sprachdateien aktualisiert werden. Führe dazu folgende Befehle bei aktivierter virtueller Umgebung (source venv/bin/activate) aus:

# 1. Sammelt alle markierten Strings aus dem Code und erstellt die Vorlage (messages.pot)
pybabel extract -F babel.cfg -k _l -o messages.pot routes services templates utils

# 2. Gleicht die neue Vorlage mit den bestehenden Übersetzungen (im Ordner 'translations') ab, ohne alte zu überschreiben
pybabel update -i messages.pot -d translations

# -> JETZT öffnest du z.B. translations/de/LC_MESSAGES/messages.po in einem Texteditor und trägst deine Übersetzungen bei msgstr "" ein! <-

# 3. Kompiliert die .po Textdateien in pfeilschnelle .mo Maschinendateien für den Webserver
pybabel compile -d translations

---

📚 Dokumentation

• AGENTS.md – Regelwerk und Anweisungen für KI-Coding-Agenten.
• ARCHITEKTUR.md – Detaillierte Systemarchitektur und Datenmodelle.
• docs/coding-standards.md – Header- und PyDoc-Dokumentationsstandards.
• docs/deployment.md – CI/CD-Pipeline und Docker-Deployment-Guide.
• docs/dev-guide.md – Entwickler-Handbuch, Mocking & Seeding.