---
name: Formeleon Rules
description: Projekt-Richtlinien für Formeleon
---

# Formeleon - Projekt Leitfaden (CONTINUE.md)

Willkommen im **Formeleon** Projekt! Diese Datei dient als Leitfaden und Regelwerk für Entwickler und KI-Assistenten (wie Continue.dev), die an dieser Codebasis arbeiten.

## 1. Projektübersicht

 **Formeleon** ist ein mandantenfähiges Formular-Service-System (Multi-tenant Form Generator & Backend API).
Es dient dazu, Formular-Submissions von externen Mandanten-Webseiten entgegenzunehmen, diese vor Bot-Spam zu schützen (via Google reCAPTCHA v3), die Daten isoliert nach Mandanten zu speichern und ein Admin-Dashboard zur Verwaltung bereitzustellen.

**Kern-Technologien:**
*   **Backend:** Python 3, Flask
*   **Datenbank:** PostgreSQL/SQLite via Flask-SQLAlchemy, Migrationen via Flask-Migrate
*   **Authentifizierung:** Zitadel via OIDC (OAuth2)
*   **Frontend (Admin):** Mithril.js, Bootstrap (CSS)
*   **Frontend (Public):** Leichtgewichtiges JS-Embed-Snippet
*   **Infrastruktur:** Docker / Docker Compose

**Architektur-Ansatz:**
Das Backend ist entkoppelt und nutzt das Flask Blueprint-Muster.
*   `api`: Public Form API für das Entgegennehmen von Daten.
*   `admin`: Dashboard zur Verwaltung.
*   `auth`: OIDC/Zitadel Handler.

---

## 2. Erste Schritte (Getting Started)

### Voraussetzungen
*   Docker & Docker Compose (für die einfachste lokale Umgebung)
*   Python 3.x (für lokale Entwicklung ohne Docker)
*   Eine `.env` Datei (Basis: `docs/dev-guide.md` für Mocking/Dev-Variablen)

### Lokale Entwicklung & Ausführung
Die Anwendung kann typischerweise über Docker Compose gestartet werden:
```bash
docker-compose up --build
```
*Weitere Details zur Einrichtung der Umgebung und Dev-Mocks (z.B. Mock-reCAPTCHA-Scores oder Dev-Bypass für OIDC) finden sich in `docs/dev-guide.md`.*

---

## 3. Projektstruktur

Der Code ist modular (Blueprint-Muster) strukturiert. **Es gibt keine monolithische `app.py` für die Routen-Logik.**

*   `app.py`: Anwendungs-Initialisierung & Blueprint-Registrierung.
*   `models.py`: SQLAlchemy Datenmodelle.
*   `routes/`: Flask Blueprints.
    *   `api.py` (`@api_bp`): Public Submissions & Handshake.
    *   `admin.py` (`@admin_bp`): Admin Panel & Config.
    *   `auth.py` (`@auth_bp`): OIDC / Zitadel Handler.
*   `services/`: Ausgelagerte Geschäftslogik.
    *   `recaptcha.py`: reCAPTCHA Validation & Mocking.
    *   `exporter.py`: Stream-Export Logik (CSV/JSON/YAML).
    *   `mailer.py`: E-Mail Versand.
*   `static/`: Frontend Assets (JS Snippets, Mithril.js Admin UI, CSS).
*   `docs/`: Umfangreiche Projektdokumentation.
*   `AGENTS.md`: Wichtige Instruktionen für KI-Assistenten.
*   `ARCHITEKTUR.md`: Detaillierte Systemarchitektur.

---

## 4. Entwicklungs-Workflow & Code-Standards

**DIESE REGELN SIND VERBINDLICH FÜR ALLE ENTWICKLER UND KI-AGENTEN!**

1.  **Sprache:**
    *   Code (Variablen, Funktionen, Modulnamen, Code-Kommentare): **Englisch**.
    *   Dokumentation (Markdown, umfangreiche Architektur-Dokus): **Deutsch**.
2.  **Dateiköpfe:**
    Jede neu erstellte oder modifizierte Quelltext-Datei (`.py`, `.j2`, `.html`, `.js`, `.css`) **MUSS** den standardisierten Dateikopf tragen.
    *   Autor: `Björn Runden <br@runden.net>`
    *   Siehe genaue Formate in `docs/coding-standards.md`.
3.  **Dokumentationspflicht (PyDoc & Jinja2):**
    *   Jede Klasse, Funktion und Methode in Python muss PyDoc-Docstrings erhalten.
    *   Logikführende Jinja2-Templates (Schleifen, Makros, etc.) müssen kommentiert werden.
4.  **Datenbank & ORM:**
    *   Zugriff **NIEMALS** direkt über Roh-SQL.
    *   **AUSSCHLIESSLICH** über Flask-SQLAlchemy arbeiten.
    *   Schema-Änderungen über Flask-Migrate (`flask db migrate`) abbilden.
5.  **Git & Branching:**
    *   Entwicklung erfolgt ausschließlich auf dem Branch `main`.
    *   Merges auf `stable` sind der CI/CD-Pipeline vorbehalten.
6.  **Modularität:**
    *   Neue Routen müssen im entsprechenden Blueprint (`routes/auth.py`, `routes/api.py`, `routes/admin.py`) registriert werden.

---

## 5. Schlüsselkonzepte & Datenmodell

*   **Multi-Tenancy (Mandantenfähigkeit):** Logische Trennung auf Datenbankebene über `tenant_id` (`FormConfig`, `Submission`, `User`).
*   **Public Keys:** Format `pk_live_<hash>`. Enthalten intern einen SHA-basierten Verweis auf die `tenant_id`.
*   **Flexible Payloads:** Formulardaten werden in einem JSON-Payload-Feld (`Submission.Payload`) gespeichert, um Schema-Migrationen bei Formularänderungen zu vermeiden.
*   **RBAC (Role-Based Access Control):** Lokale Rechteverwaltung in der DB (`admin`, `tenant_admin`, `user`, `viewer`) verknüpft über die E-Mail-Adresse. Zitadel (OIDC) liefert nur Identität (Kein Rollen-Mapping aus Token-Claims!).
*   **Bot-Schutz:** Google reCAPTCHA v3. Schwellenwert konfigurierbar. Unter Schwellenwert wird die Submission als `flagged_as_spam` gespeichert und ein HTTP 400 zurückgegeben.

---

## 6. Frontend Einbindung (Das Embed Snippet)

Mandanten binden das Formular wie folgt ein:
```html
<script src="https://formeleon.domain/embed.js" data-form-id="123" data-public-key="pk_live_xyz"></script>
<div id="formeleon-form"></div>
```
Das Snippet (`static/js/...`) nutzt die Fetch API für einen Handshake (prüft `Origin`), injiziert das HTML direkt ins DOM und fängt das Submit-Event ab, um ein reCAPTCHA Token zu holen und die Daten an `/api/v1/...` zu senden.

---

## 7. Referenzen & Weiterführende Dokumentation

Bevor du spezifische Module bearbeitest, lies bitte die entsprechenden Detail-Dokumente:

*   **KI-Agenten Steuerzentrale:** `AGENTS.md`
*   **System-Architektur & DB:** `ARCHITEKTUR.md`
*   **Feinkonzept & Spezifikation:** `docs/feinkonzept.md`
*   **Header & PyDoc Standards:** `docs/coding-standards.md`
*   **Dev-Environment & Mocks:** `docs/dev-guide.md`
*   **CI/CD & Deployment:** `docs/deployment.md`
*   **Git-Workflow:** `docs/git-workflow.md`

*(Hinweis: Für konkrete Troubleshooting-Fälle, lies bitte die jeweiligen Markdown-Dateien im `docs/` Verzeichnis, z.B. bezüglich der Entwicklungsumgebung in der `dev-guide.md`)*