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:

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

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

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/

📚 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.

3.6 KiB Raw Blame History Unescape Escape