refactor: restructure

monorepo with apps/ and services/
  directories

apps/uload/docs/auth-implementation-notes.md

@@ -0,0 +1,189 @@
+# 🔐 Authentication Implementation Notes für ulo.ad
+
+## Übersicht
+
+Diese Dokumentation beschreibt wichtige Implementierungsdetails und Lösungen für häufige Probleme im Authentication-Flow von ulo.ad.
+
+---
+
+## ⚠️ Wichtige SvelteKit + PocketBase Quirks
+
+### 1. Login Redirect Problem
+
+**Problem:**
+Nach erfolgreichem Login wird fälschlicherweise "Invalid email or password" angezeigt, obwohl der Login funktioniert hat.
+
+**Ursache:**
+SvelteKit's `redirect()` Funktion wirft intern eine Exception. Wenn diese im try-catch-Block steht, wird sie als Login-Fehler interpretiert.
+
+**❌ Falsch:**
+
+```typescript
+// src/routes/login/+page.server.ts
+try {
+	await locals.pb.collection('users').authWithPassword(email, password);
+	redirect(303, '/dashboard'); // ⚠️ Wirft Exception!
+} catch (err) {
+	return fail(400, { error: 'Invalid email or password' }); // Fängt redirect!
+}
+```
+
+**✅ Richtig:**
+
+```typescript
+// src/routes/login/+page.server.ts
+try {
+	await locals.pb.collection('users').authWithPassword(email, password);
+	locals.user = locals.pb.authStore.model;
+} catch (err) {
+	console.error('Login error:', err);
+	return fail(400, { error: 'Invalid email or password' });
+}
+
+// Redirect AUSSERHALB des try-catch!
+redirect(303, '/dashboard');
+```
+
+---
+
+### 2. E-Mail Verifizierung Fehler
+
+**Problem:**
+PocketBase verifiziert den User erfolgreich, wirft aber trotzdem einen Fehler beim `confirmVerification()` Aufruf.
+
+**Lösung:**
+
+```typescript
+// src/routes/verify-email/+page.server.ts
+try {
+	await pb.collection('users').confirmVerification(token);
+	redirect(303, '/login?verified=true');
+} catch (error) {
+	// PocketBase wirft IMMER einen Fehler, auch bei Erfolg!
+	if (errorMessage.includes('expired')) {
+		redirect(303, '/login?error=token-expired');
+	} else {
+		// Behandle als Erfolg
+		redirect(303, '/login?verified=true');
+	}
+}
+```
+
+---
+
+### 3. Registrierung mit E-Mail-Versand
+
+**Problem:**
+E-Mail-Verifizierung wird nicht gesendet, wenn nach der Registrierung Auth-Operationen durchgeführt werden.
+
+**Reihenfolge ist kritisch:**
+
+```typescript
+// src/routes/register/+page.server.ts
+
+// 1. User erstellen
+const newUser = await pb.collection('users').create({...});
+
+// 2. ZUERST E-Mail senden (vor Auth-Operationen!)
+await pb.collection('users').requestVerification(email);
+
+// 3. DANN andere Operationen (z.B. Profil-Card erstellen)
+await pb.collection('users').authWithPassword(email, password);
+// ... weitere Operationen
+pb.authStore.clear();
+
+// 4. Zur Login-Seite weiterleiten (KEIN Auto-Login!)
+redirect(303, '/login?registered=true');
+```
+
+---
+
+## 📋 Best Practices
+
+### Redirects in SvelteKit
+
+1. **Immer außerhalb von try-catch**: Redirects gehören nicht in try-catch-Blöcke
+2. **Return vs. Throw**: `redirect()` wirft eine Exception, `return fail()` gibt einen Wert zurück
+3. **Error-First**: Erst alle Fehler behandeln, dann erfolgreiche Redirects
+
+### PocketBase Authentication
+
+1. **authStore.clear()**: Immer aufrufen wenn temporäre Auth benötigt wurde
+2. **locals.user**: Nach Login setzen für sofortige Verfügbarkeit
+3. **Verification**: Fehler als Erfolg behandeln (PocketBase Quirk)
+
+### E-Mail-Versand
+
+1. **Reihenfolge beachten**: E-Mails vor Auth-Operationen senden
+2. **Template-Komplexität**: Bei Problemen vereinfachte Templates ohne Unicode verwenden
+3. **Error-Handling**: E-Mail-Fehler nicht den ganzen Flow blockieren lassen
+
+---
+
+## 🐛 Debugging-Tipps
+
+### Login-Probleme
+
+```bash
+# Console logs prüfen
+console.error('Login error:', err);
+
+# PocketBase Admin prüfen
+http://localhost:8090/_/
+# → Logs → Auth Logs
+```
+
+### E-Mail-Probleme
+
+```bash
+# SMTP Logs in PocketBase
+http://localhost:8090/_/
+# → Logs → Mails
+
+# Template testen mit einfacher Version
+docs/mail/email-templates-simplified.md
+```
+
+### Session-Probleme
+
+```javascript
+// Session-Status prüfen
+console.log('Auth store valid:', locals.pb.authStore.isValid);
+console.log('Current user:', locals.pb.authStore.model);
+```
+
+---
+
+## 📁 Relevante Dateien
+
+```
+/src/routes/
+├── login/
+│   ├── +page.server.ts       # Login-Action mit korrektem Redirect
+│   └── +page.svelte          # Status-Messages für Verifizierung
+├── register/
+│   └── +page.server.ts       # Registrierung mit E-Mail-Versand
+├── verify-email/
+│   └── +page.server.ts       # Verifizierung mit Fehler-als-Erfolg
+└── (app)/
+    └── +layout.server.ts     # User in locals setzen
+
+/src/hooks.server.ts          # PocketBase Client initialisieren
+```
+
+---
+
+## ✅ Checkliste für neue Auth-Features
+
+- [ ] Redirects außerhalb von try-catch
+- [ ] E-Mail-Versand vor Auth-Operationen
+- [ ] PocketBase Fehler als mögliche Erfolge behandeln
+- [ ] authStore.clear() nach temporären Auth-Operationen
+- [ ] Proper error logging für Debugging
+- [ ] User-freundliche Fehlermeldungen (bilingual)
+
+---
+
+_Erstellt: 15. Januar 2025_  
+_Version: 1.0_  
+_Für: ulo.ad Authentication System_