# Formeleon 🦎

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

*Read this in English: [README.EN.md](./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:**
   ```bash
   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:**
   ```bash
   # 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.

```bash
# 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:

```bash
# 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`](./AGENTS.md) – Regelwerk und Anweisungen für KI-Coding-Agenten.
* [`ARCHITEKTUR.md`](./ARCHITEKTUR.md) – Detaillierte Systemarchitektur und Datenmodelle.
* [`docs/coding-standards.md`](./docs/coding-standards.md) – Header- und PyDoc-Dokumentationsstandards.
* [`docs/deployment.md`](./docs/deployment.md) – CI/CD-Pipeline und Docker-Deployment-Guide.
* [`docs/dev-guide.md`](./docs/dev-guide.md) – Entwickler-Handbuch, Mocking & Seeding.