diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8ac3d80
--- /dev/null
+++ b/README.md
@@ -0,0 +1,107 @@
+# Date-Wizard 💕
+
+Eine spielerische Web-App ("Choose Your Own Adventure") zum Planen gemeinsamer Dates – mit mobilem Design, dynamischen Aktivitäten & Terminen sowie einem Go-Microservice zum E-Mail-Versand der Reservierung.
+
+---
+
+## 📁 Projektstruktur
+
+```text
+datetest/
+├── public/                 # Statische Webseiten & Assets
+│   ├── appsettings.json    # Konfiguration der Aktivitäten & Termine
+│   ├── index.html          # Startseite ("Willst du mit mir gehen?")
+│   ├── datetime.html/.js   # Datumsauswahl (Kalender)
+│   ├── activity.html/.js   # Aktivitätsauswahl
+│   ├── name.html/.js       # Namensauswahl ("Wer bist du?")
+│   └── checkout.html/.js   # Zusammenfassung & Bestätigung
+├── main.go                 # Go-Microservice (HTTP-Server & SMTP E-Mail)
+├── go.mod                  # Go-Moduldefinition
+├── Dockerfile              # Multi-Stage Dockerfile (Alpine Runtime)
+├── docker-compose.yml      # Docker-Compose mit Traefik Labels
+├── .env.example            # Vorlage für Umgebungsvariablen
+└── .env                    # Lokale/Produktive Umgebungsvariablen (nicht ins Git committen)
+```
+
+---
+
+## ⚙️ Konfiguration
+
+### 1. E-Mail & Server `.env` anlegen
+
+Kopiere `.env.example` zu `.env`:
+
+```bash
+cp .env.example .env
+```
+
+Trage in der `.env` deine Server- und SMTP-Zugangsdaten ein:
+
+| Variable | Beschreibung | Beispiel |
+| :--- | :--- | :--- |
+| `PORT` | HTTP-Port des Go-Servers | `8080` |
+| `WEB_DIR` | Verzeichnis der statischen Assets | `public` |
+| `SMTP_HOST` | Postausgangsserver (SMTP) | `mail.example.com` |
+| `SMTP_PORT` | SMTP-Port (Standard meist 587 oder 465) | `587` |
+| `SMTP_USER` | Benutzername / E-Mail für SMTP-Auth | `absender@example.com` |
+| `SMTP_PASS` | Passwort des SMTP-Kontos | `secretpassword` |
+| `TO_EMAIL` | Ziel-Adresse für eingegangene Date-Anfragen | `ziel@example.com` |
+| `FROM_EMAIL` | Absender-Adresse für die Benachrichtigung | `absender@example.com` |
+
+*(Hinweis: Wenn `SMTP_HOST` oder `TO_EMAIL` leer bleiben, läuft der Server im Testmodus ohne E-Mail-Versand.)*
+
+### 2. Aktivitäten & Termine anpassen (`public/appsettings.json`)
+
+Passe in `public/appsettings.json` die zur Auswahl stehenden Aktivitäten sowie die verfügbaren Tage an:
+
+- **`activities`**: Liste von Objekten mit `name`, `icon` (Unicode Emoji) und `type` (`short` oder `long`).
+- **`availableDates`**: Liste von verfügbaren Tagen mit `date` (`YYYY-MM-DD`) und `type` (`short` oder `long`).
+- **`names`**: Optional vordefinierte Namen zur Auswahl (ist die Liste leer, wird ein Standard-Fallback angeboten).
+
+---
+
+## 🚀 Inbetriebnahme
+
+### Option A: Mit Docker Compose (Empfohlen)
+
+1. `.env` wie oben beschrieben anpassen.
+2. Container erstellen und starten:
+
+   ```bash
+   docker-compose up -d --build
+   ```
+
+3. Die Anwendung ist unter `http://localhost:8080` erreichbar.
+
+#### Traefik / Reverse Proxy
+
+`docker-compose.yml` enthält bereits Traefik-Labels. Passe bei Bedarf die Domain an:
+
+```yaml
+- "traefik.http.routers.date-wizard.rule=Host(`date.deine-domain.de`)"
+```
+
+---
+
+### Option B: Direkt mit Go (Lokal)
+
+#### Voraussetzungen
+- Installed Go SDK (Version 1.22 oder neuer)
+
+1. Abhängigkeiten prüfen & kompilieren:
+
+   ```bash
+   go run main.go
+   ```
+
+2. Die Anwendung startet auf dem in `.env` definierten Port (z. B. `http://localhost:8080`).
+
+---
+
+## 📱 Ablauf der Anwendung
+
+1. **Startseite (`index.html`)**: Spielerische Frage mit Ja/Nein-Interaktion.
+2. **Datumsauswahl (`datetime.html`)**: Interaktiver Kalender mit Markierung von verfügbaren Tagen (`short`/`long`).
+3. **Aktivitätsauswahl (`activity.html`)**: Auswahl passender Aktivitäten je nach verbleibender Zeit am gewählten Tag.
+4. **Namensauswahl (`name.html`)**: Abfrage "Wer bist du?".
+5. **Checkout & Bestätigung (`checkout.html`)**: Finale Übersicht und Absenden der Reservierung (überträgt Daten an `/api/submit` und löst den E-Mail-Versand aus).