initiales Projektsetup als skeleton für fresh flask + architecture

README.md

@@ -1,3 +1,60 @@
-# README.md
-## Formeleon. Sichere Formulare nach Maß
- 
+# 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.12, 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 (Dev-Mode)
+
+1. **Repository klonen & Umgebung einrichten:**
+   ```bash
+   python3 -m venv venv
+   source venv/bin/activate
+   pip install -r requirements.txt
+   ```
+
+2. **Umgebungsvariablen konfigurieren:**
+   ```bash
+   cp .env.example .env
+   # DEV_MODE=true ist standardmäßig aktiviert
+   ```
+
+3. **Datenbank initialisieren & starten:**
+   ```bash
+   flask db upgrade
+   flask run --port=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.