docs: consolidate documentation into organized structure

- Move 12 markdown files from root to docs/ subdirectories
- Organize documentation by category:
  • docs/troubleshooting/ (1 file)  - Technical troubleshooting guides
  • docs/deployment/      (4 files) - Deployment and security documentation
  • docs/guides/          (3 files) - Feature-specific guides
  • docs/planning/        (4 files) - Planning and improvement proposals

Root directory cleanup:
- Reduced from 16 to 4 markdown files in root
- Only essential project files remain:
  • CLAUDE.md (AI instructions)
  • README.md (Main project readme)
  • CLEANUP_PLAN.md (Current cleanup plan)
  • SRC_STRUCTURE_IMPROVEMENTS.md (Structure improvements)

This improves:
✅ Documentation discoverability
✅ Logical organization by purpose
✅ Clean root directory
✅ Better maintainability

docs/planning/TODO.md

@@ -0,0 +1,289 @@
+# Framework Improvement Todo List
+
+This document outlines the planned improvements for the michaelschiemer.de framework, organized by category and priority. Each task includes an estimated effort level and current status.
+
+## How to Use This List
+
+- **Priority**: (P1: Critical, P2: High, P3: Medium, P4: Low)
+- **Effort**: (S: Small, M: Medium, L: Large, XL: Extra Large)
+- **Status**: TODO, IN_PROGRESS, DONE
+- Review this list during sprint planning to select the next tasks to work on
+- Update task status as work progresses
+- Add new tasks as they are identified during development
+
+## Testing Improvements
+
+### P1: Critical Testing Tasks
+
+- [ ] **Increase unit test coverage for security components** (M)
+  - Focus on WAF functionality
+  - Test edge cases for security filters
+  - Ensure proper validation of security rules
+
+- [ ] **Implement integration tests for critical paths** (L)
+  - Authentication flow
+  - Payment processing
+  - Data persistence operations
+
+### P2: High Priority Testing Tasks
+
+- [ ] **Set up performance testing infrastructure** (L)
+  - Establish performance baselines
+  - Create automated performance test suite
+  - Integrate with CI/CD pipeline
+
+- [ ] **Improve test coverage for Cache system** (M)
+  - Test AsyncAwareCache
+  - Test CompressionCacheDecorator
+  - Test MultiLevelCache
+
+- [ ] **Enhance HTTP component test coverage** (M)
+  - Request/Response handling
+  - Middleware execution
+  - Route resolution
+
+### P3: Medium Priority Testing Tasks
+
+- [ ] **Create more test fixtures and factories** (S)
+  - Standardize test data generation
+  - Implement faker integration for test data
+
+- [ ] **Implement browser-based end-to-end tests** (XL)
+  - Set up Selenium or Cypress
+  - Create test scenarios for critical user journeys
+
+## Performance Optimizations
+
+### P1: Critical Performance Tasks
+
+- [ ] **Optimize cache strategy implementation** (M)
+  - Review and improve AsyncCacheAdapter
+  - Enhance MultiLevelCache configuration
+  - Implement cache warming for critical data
+
+- [ ] **Implement query optimization for database operations** (L)
+  - Identify and fix N+1 query issues
+  - Add appropriate indexes
+  - Optimize JOIN operations
+
+### P2: High Priority Performance Tasks
+
+- [ ] **Implement lazy loading for resource-intensive components** (M)
+  - Identify components suitable for lazy loading
+  - Refactor to support lazy initialization
+
+- [ ] **Set up regular performance profiling** (M)
+  - Configure Xdebug profiling
+  - Implement Blackfire integration
+  - Create performance dashboards
+
+### P3: Medium Priority Performance Tasks
+
+- [ ] **Optimize asset delivery** (M)
+  - Implement proper caching headers
+  - Set up CDN integration
+  - Optimize image loading
+
+- [ ] **Reduce framework bootstrap time** (L)
+  - Analyze startup performance
+  - Implement service container optimizations
+  - Reduce unnecessary initializations
+
+## Security Improvements
+
+### P1: Critical Security Tasks
+
+- [ ] **Conduct comprehensive security audit** (XL)
+  - Review authentication mechanisms
+  - Audit authorization controls
+  - Check for OWASP Top 10 vulnerabilities
+
+- [ ] **Implement automated dependency scanning** (S)
+  - Set up Composer security checks
+  - Integrate with CI/CD pipeline
+  - Create alerting for vulnerable dependencies
+
+### P2: High Priority Security Tasks
+
+- [ ] **Enhance WAF functionality** (L)
+  - Improve rule definitions
+  - Add more sophisticated attack detection
+  - Implement rate limiting
+
+- [ ] **Implement Content Security Policy** (M)
+  - Define appropriate CSP rules
+  - Test CSP implementation
+  - Monitor CSP violations
+
+### P3: Medium Priority Security Tasks
+
+- [ ] **Improve CSRF protection** (M)
+  - Review current implementation
+  - Enhance token generation and validation
+  - Add automatic CSRF protection to forms
+
+- [ ] **Implement security headers** (S)
+  - Configure appropriate security headers
+  - Test header implementation
+  - Document security header strategy
+
+## Code Modernization
+
+### P1: Critical Modernization Tasks
+
+- [ ] **Upgrade to latest PHP version** (L)
+  - Identify compatibility issues
+  - Update code to use new language features
+  - Test thoroughly after upgrade
+
+- [ ] **Implement strict typing throughout the codebase** (XL)
+  - Add strict_types declaration to all files
+  - Add proper type hints to all methods
+  - Fix any type-related issues
+
+### P2: High Priority Modernization Tasks
+
+- [ ] **Refactor to use PHP 8.x features** (L)
+  - Implement named arguments where appropriate
+  - Use union types for better type safety
+  - Utilize attributes for metadata
+
+- [ ] **Standardize error handling** (M)
+  - Create consistent exception hierarchy
+  - Implement proper error logging
+  - Improve error messages
+
+### P3: Medium Priority Modernization Tasks
+
+- [ ] **Implement more value objects** (M)
+  - Identify primitive obsession issues
+  - Create appropriate value objects
+  - Refactor code to use value objects
+
+- [ ] **Refactor to use more immutable objects** (L)
+  - Identify mutable state issues
+  - Implement immutable alternatives
+  - Update code to work with immutable objects
+
+## Documentation Improvements
+
+### P1: Critical Documentation Tasks
+
+- [ ] **Create comprehensive API documentation** (XL)
+  - Document all public APIs
+  - Include examples and use cases
+  - Ensure documentation is up-to-date
+
+- [ ] **Improve code comments and docblocks** (L)
+  - Add/update PHPDoc blocks
+  - Document complex algorithms
+  - Explain architectural decisions
+
+### P2: High Priority Documentation Tasks
+
+- [ ] **Create architecture documentation** (L)
+  - Document overall system architecture
+  - Create component diagrams
+  - Document design patterns used
+
+- [ ] **Improve developer onboarding documentation** (M)
+  - Create step-by-step setup guide
+  - Document development workflow
+  - Create troubleshooting guide
+
+### P3: Medium Priority Documentation Tasks
+
+- [ ] **Create user documentation** (L)
+  - Document user-facing features
+  - Create user guides
+  - Add screenshots and examples
+
+- [ ] **Document testing strategy** (M)
+  - Explain testing approach
+  - Document test organization
+  - Provide examples of good tests
+
+## DevOps and CI/CD
+
+### P1: Critical DevOps Tasks
+
+- [ ] **Enhance CI/CD pipeline** (L)
+  - Add automated testing
+  - Implement deployment gates
+  - Add security scanning
+
+- [ ] **Improve deployment process** (M)
+  - Enhance deployment script
+  - Add rollback capabilities
+  - Implement blue/green deployments
+
+### P2: High Priority DevOps Tasks
+
+- [ ] **Set up comprehensive monitoring** (L)
+  - Implement application performance monitoring
+  - Set up error tracking
+  - Create alerting system
+
+- [ ] **Improve Docker configuration** (M)
+  - Optimize Docker images
+  - Enhance Docker Compose setup
+  - Implement multi-stage builds
+
+### P3: Medium Priority DevOps Tasks
+
+- [ ] **Implement infrastructure as code** (XL)
+  - Set up Terraform or similar
+  - Document infrastructure
+  - Automate infrastructure provisioning
+
+- [ ] **Create development environment parity** (M)
+  - Ensure dev/prod environment similarity
+  - Document environment differences
+  - Simplify environment setup
+
+## Framework Components Overhaul
+
+### P1: Critical Component Tasks
+
+- [ ] **Enhance Mail system based on Attachment.php** (M)
+  - Improve attachment handling
+  - Add support for templates
+  - Implement mail queuing
+
+- [ ] **Optimize Cache system** (L)
+  - Refactor AsyncAwareCache
+  - Enhance CompressionCacheDecorator
+  - Improve MultiLevelCache
+
+### P2: High Priority Component Tasks
+
+- [ ] **Improve Validation system** (L)
+  - Enhance ValidationRule implementation
+  - Add more validation rules
+  - Improve validation error messages
+
+- [ ] **Enhance Router functionality** (M)
+  - Optimize route matching
+  - Improve middleware handling
+  - Add better support for route groups
+
+### P3: Medium Priority Component Tasks
+
+- [ ] **Refactor Discovery service** (M)
+  - Improve DiscoveryServiceBootstrapper
+  - Enhance service registration
+  - Optimize service resolution
+
+- [ ] **Enhance Core components** (L)
+  - Improve ProgressMeter
+  - Refactor value objects
+  - Optimize core utilities
+
+## Progress Tracking
+
+- Total tasks: 42
+- Completed: 0
+- In progress: 0
+- Remaining: 42
+
+Last updated: 2025-08-01

docs/planning/docs-implementation-plan.md

@@ -0,0 +1,163 @@
+# Dokumentationsstruktur-Implementierungsplan
+
+## Zusammenfassung
+
+Basierend auf der Analyse der bestehenden Dokumentation und der Erstellung neuer Dokumentationsinhalte wird folgende Implementierungsstrategie für die neue Dokumentationsstruktur empfohlen. Dieser Plan beschreibt die finale Verzeichnisstruktur, den Migrationsprozess für bestehende Inhalte und einen Zeitplan für die Umsetzung.
+
+## Finale Verzeichnisstruktur
+
+```
+docs/
+├── README.md                      # Übersicht und Navigationshilfe (basierend auf new-docs-README.md)
+├── getting-started/               # Einstiegsdokumentation
+│   ├── installation.md            # Installationsanleitung
+│   ├── configuration.md           # Konfigurationsanleitung
+│   └── first-steps.md             # Erste Schritte mit dem Framework
+├── architecture/                  # Architektur-Dokumentation
+│   ├── overview.md                # Architekturübersicht
+│   ├── components.md              # Hauptkomponenten
+│   └── patterns.md                # Verwendete Entwurfsmuster
+├── components/                    # Komponentendokumentation
+│   ├── analytics/                 # Analytics-Komponente (bestehende Dokumentation)
+│   │   ├── index.md               # Übersicht (bestehende Datei)
+│   │   ├── configuration.md       # Konfiguration
+│   │   └── examples.md            # Beispiele
+│   ├── validation/                # Validierungs-Komponente
+│   │   ├── index.md               # Übersicht (basierend auf new-docs-validation-index.md)
+│   │   ├── rules.md               # Validierungsregeln
+│   │   └── examples.md            # Beispiele
+│   ├── security/                  # Sicherheits-Komponente
+│   │   ├── index.md               # Übersicht (basierend auf new-docs-security-index.md)
+│   │   ├── csrf-protection.md     # CSRF-Schutz im Detail
+│   │   ├── security-headers.md    # Security Headers und CSP
+│   │   └── request-signing.md     # Request Signing API
+│   ├── waf/                       # WAF-Komponente
+│   │   ├── index.md               # Übersicht (basierend auf new-docs-waf-index.md)
+│   │   ├── machine-learning.md    # ML-Funktionalität (basierend auf new-docs-waf-machine-learning.md)
+│   │   └── configuration.md       # Konfiguration
+│   └── ...                        # Weitere Komponenten
+├── guides/                        # Entwickleranleitungen
+│   ├── routing.md                 # Routing-Anleitung
+│   ├── controllers.md             # Controller-Anleitung
+│   ├── validation.md              # Validierungs-Anleitung
+│   ├── security.md                # Sicherheits-Anleitung
+│   └── ...                        # Weitere Anleitungen
+├── api/                           # API-Dokumentation
+│   ├── index.md                   # API-Übersicht
+│   └── ...                        # Generierte API-Docs
+├── contributing/                  # Beitragsrichtlinien
+│   ├── code-style.md              # Coding-Standards
+│   ├── pull-requests.md           # PR-Prozess
+│   └── documentation.md           # Dokumentationsrichtlinien
+└── roadmap/                       # Projektplanung
+    ├── features.md                # Feature-Tracking (basierend auf new-docs-features.md)
+    ├── tasks.md                   # Task-Tracking (basierend auf new-docs-tasks.md)
+    └── milestones.md              # Meilensteine
+```
+
+## Migrationsstrategie
+
+### 1. Vorbereitung
+
+1. **Backup der bestehenden Dokumentation**
+   - Erstellen Sie ein vollständiges Backup des aktuellen `docs`-Ordners
+   - Markieren Sie diesen Backup mit einem Zeitstempel
+
+2. **Einrichtung der neuen Struktur**
+   - Erstellen Sie die neue Verzeichnisstruktur in einem temporären Ordner (z.B. `new-docs`)
+   - Kopieren Sie die README.md-Datei als Einstiegspunkt
+
+### 2. Migration bestehender Inhalte
+
+1. **Identifizierte wertvolle Inhalte**
+   - Analytics-Dokumentation (`docs/framework/analytics/index.md`)
+   - Andere aktuelle und korrekte Dokumentation (nach Bedarf)
+
+2. **Migrationsprozess**
+   - Kopieren Sie die Analytics-Dokumentation in den neuen Pfad (`components/analytics/index.md`)
+   - Aktualisieren Sie interne Links, um auf die neue Struktur zu verweisen
+   - Passen Sie das Format bei Bedarf an die neue Dokumentationsvorlage an
+
+3. **Neue Dokumentation integrieren**
+   - Fügen Sie die neu erstellten Dokumentationsdateien in die entsprechenden Verzeichnisse ein:
+     - `new-docs-README.md` → `README.md`
+     - `new-docs-validation-index.md` → `components/validation/index.md`
+     - `new-docs-security-index.md` → `components/security/index.md`
+     - `new-docs-waf-index.md` → `components/waf/index.md`
+     - `new-docs-waf-machine-learning.md` → `components/waf/machine-learning.md`
+     - `new-docs-features.md` → `roadmap/features.md`
+     - `new-docs-tasks.md` → `roadmap/tasks.md`
+
+### 3. Qualitätssicherung
+
+1. **Überprüfung der Links**
+   - Validieren Sie alle internen Links in der neuen Dokumentation
+   - Stellen Sie sicher, dass sie auf die korrekten Pfade in der neuen Struktur verweisen
+
+2. **Konsistenzprüfung**
+   - Überprüfen Sie die Konsistenz von Stil, Format und Terminologie
+   - Stellen Sie sicher, dass alle Dokumentationsdateien den gleichen Standards folgen
+
+3. **Vollständigkeitsprüfung**
+   - Identifizieren Sie fehlende Dokumentation und erstellen Sie Platzhalter mit TODOs
+
+### 4. Bereitstellung
+
+1. **Ersetzung des bestehenden Ordners**
+   - Benennen Sie den bestehenden `docs`-Ordner um (z.B. in `docs-old`)
+   - Benennen Sie den neuen `new-docs`-Ordner in `docs` um
+
+2. **Ankündigung und Kommunikation**
+   - Informieren Sie das Entwicklungsteam über die neue Dokumentationsstruktur
+   - Heben Sie die wichtigsten Änderungen und Verbesserungen hervor
+
+## Zeitplan für die Implementierung
+
+### Phase 1: Vorbereitung und Struktur (1-2 Tage)
+- Backup erstellen
+- Neue Verzeichnisstruktur einrichten
+- README.md und Navigationshilfen erstellen
+
+### Phase 2: Migration und Integration (2-3 Tage)
+- Bestehende Analytics-Dokumentation migrieren
+- Neue Dokumentation integrieren
+- Links und Verweise aktualisieren
+
+### Phase 3: Qualitätssicherung (1-2 Tage)
+- Links validieren
+- Konsistenz prüfen
+- Fehlende Dokumentation identifizieren
+
+### Phase 4: Bereitstellung und Nachverfolgung (1 Tag)
+- Alte Dokumentation ersetzen
+- Team informieren
+- Feedback sammeln und Anpassungen vornehmen
+
+## Empfehlungen für die Implementierung
+
+### Timing
+Die beste Zeit für die Implementierung ist:
+- Zu Beginn einer neuen Entwicklungsphase
+- Nach Abschluss größerer Feature-Entwicklungen
+- Vor dem Onboarding neuer Teammitglieder
+
+### Ansatz
+1. **Inkrementelle Validierung**
+   - Lassen Sie Teammitglieder Teile der neuen Dokumentation vor der vollständigen Bereitstellung überprüfen
+   - Sammeln Sie Feedback und nehmen Sie Anpassungen vor
+
+2. **Automatisierung**
+   - Implementieren Sie Dokumentationsvalidierung in der CI/CD-Pipeline
+   - Automatisieren Sie die Überprüfung von Links und Formatierung
+
+3. **Kontinuierliche Verbesserung**
+   - Etablieren Sie einen Prozess für regelmäßige Dokumentationsaktualisierungen
+   - Integrieren Sie Dokumentationsaktualisierungen in den Pull-Request-Prozess
+
+## Fazit
+
+Die vorgeschlagene Implementierungsstrategie bietet einen strukturierten Ansatz zur Ersetzung der bestehenden Dokumentation durch eine konsistente, gut organisierte neue Struktur. Durch die sorgfältige Migration wertvoller bestehender Inhalte und die Integration der neu erstellten Dokumentation wird sichergestellt, dass keine wichtigen Informationen verloren gehen.
+
+Der Zeitplan ist realistisch und berücksichtigt alle notwendigen Schritte für eine erfolgreiche Migration. Die Empfehlungen für Timing und Ansatz helfen, Störungen zu minimieren und die Akzeptanz im Team zu maximieren.
+
+Nach der Implementierung wird die Dokumentation besser strukturiert, aktueller und leichter zu navigieren sein, was die Entwicklererfahrung verbessert und die Einarbeitung neuer Teammitglieder erleichtert.

docs/planning/docs-replacement-recommendation.md

@@ -0,0 +1,137 @@
+# Empfehlung zur Ersetzung des docs-Ordners
+
+## Zusammenfassung
+
+Basierend auf der Analyse des aktuellen Zustands der Dokumentation und dem bereits erstellten Dokumentations-Aktualisierungsvorschlag empfehle ich, den vorhandenen `docs`-Ordner durch eine neue, strukturierte Dokumentationsorganisation zu ersetzen. Diese Empfehlung berücksichtigt den aktuellen Zustand der Dokumentation, die identifizierten Probleme und die Vorteile einer konsistenten, gut organisierten Dokumentationsstruktur.
+
+## Analyse des aktuellen Zustands
+
+Die Analyse des `docs`-Ordners hat folgende Probleme aufgezeigt:
+
+1. **Inkonsistente Struktur**: Die Dokumentation folgt keinem einheitlichen Organisationsprinzip.
+2. **Veraltete Inhalte**: Ein Großteil der Dokumentation (insbesondere Tracking-Dokumente wie `features.md` und `tasks.md`) ist veraltet und spiegelt nicht den aktuellen Implementierungsstatus wider.
+3. **Uneinheitliches Format**: Die Dokumentation verwendet verschiedene Formate und Stile.
+4. **Fehlerhafte Verweise**: Viele Links innerhalb der Dokumentation sind ungültig oder verweisen auf nicht existierende Dateien.
+5. **Unvollständige Abdeckung**: Wichtige Komponenten sind nicht oder nur unzureichend dokumentiert.
+
+Gleichzeitig gibt es wertvolle Dokumentation (wie die Analytics-Komponente), die erhalten und in die neue Struktur integriert werden sollte.
+
+## Empfehlung: Vollständige Ersetzung mit Migration wertvoller Inhalte
+
+Ich empfehle eine vollständige Ersetzung des `docs`-Ordners mit einer neuen, strukturierten Organisation, kombiniert mit einer sorgfältigen Migration wertvoller Inhalte aus der bestehenden Dokumentation.
+
+### Vorteile dieses Ansatzes:
+
+1. **Klarer Neuanfang**: Eine vollständige Ersetzung ermöglicht einen klaren Schnitt und die Etablierung eines neuen Dokumentationsstandards ohne Legacy-Probleme.
+2. **Konsistente Struktur**: Die neue Dokumentation kann von Grund auf mit einer durchdachten, konsistenten Struktur aufgebaut werden.
+3. **Aktualitätsgarantie**: Alle Dokumente in der neuen Struktur werden überprüft und aktualisiert, was die Zuverlässigkeit der Dokumentation erhöht.
+4. **Verbesserte Auffindbarkeit**: Eine logische Organisation erleichtert das Auffinden relevanter Dokumentation.
+5. **Einfachere Wartung**: Eine konsistente Struktur und Format erleichtern die zukünftige Wartung und Aktualisierung.
+
+### Vorgeschlagene neue Dokumentationsstruktur
+
+```
+docs/
+├── README.md                      # Übersicht und Navigationshilfe
+├── getting-started/               # Einstiegsdokumentation
+│   ├── installation.md            # Installationsanleitung
+│   ├── configuration.md           # Konfigurationsanleitung
+│   └── first-steps.md             # Erste Schritte mit dem Framework
+├── architecture/                  # Architektur-Dokumentation
+│   ├── overview.md                # Architekturübersicht
+│   ├── components.md              # Hauptkomponenten
+│   └── patterns.md                # Verwendete Entwurfsmuster
+├── components/                    # Komponentendokumentation
+│   ├── analytics/                 # Analytics-Komponente
+│   │   ├── index.md               # Übersicht
+│   │   ├── configuration.md       # Konfiguration
+│   │   └── examples.md            # Beispiele
+│   ├── validation/                # Validierungs-Komponente
+│   │   ├── index.md               # Übersicht
+│   │   ├── rules.md               # Validierungsregeln
+│   │   └── examples.md            # Beispiele
+│   ├── waf/                       # WAF-Komponente
+│   │   ├── index.md               # Übersicht
+│   │   ├── machine-learning.md    # ML-Funktionalität
+│   │   └── configuration.md       # Konfiguration
+│   └── ...                        # Weitere Komponenten
+├── guides/                        # Entwickleranleitungen
+│   ├── routing.md                 # Routing-Anleitung
+│   ├── controllers.md             # Controller-Anleitung
+│   ├── validation.md              # Validierungs-Anleitung
+│   └── ...                        # Weitere Anleitungen
+├── api/                           # API-Dokumentation
+│   ├── index.md                   # API-Übersicht
+│   └── ...                        # Generierte API-Docs
+├── contributing/                  # Beitragsrichtlinien
+│   ├── code-style.md              # Coding-Standards
+│   ├── pull-requests.md           # PR-Prozess
+│   └── documentation.md           # Dokumentationsrichtlinien
+└── roadmap/                       # Projektplanung
+    ├── features.md                # Feature-Tracking (aktualisiert)
+    ├── tasks.md                   # Task-Tracking (aktualisiert)
+    └── milestones.md              # Meilensteine
+```
+
+### Migrationsstrategie für wertvolle Inhalte
+
+1. **Identifizierung wertvoller Inhalte**:
+   - Aktuelle Komponentendokumentation (wie Analytics)
+   - Architekturinformationen aus bestehenden Dokumenten
+   - Relevante Codebeispiele und Anleitungen
+
+2. **Transformationsprozess**:
+   - Anpassung an das neue Format und die neue Struktur
+   - Aktualisierung veralteter Informationen
+   - Korrektur fehlerhafter Links und Verweise
+   - Ergänzung fehlender Informationen
+
+3. **Qualitätssicherung**:
+   - Überprüfung aller migrierten Inhalte auf Aktualität und Korrektheit
+   - Validierung aller Links und Verweise
+   - Sicherstellung der Konsistenz mit dem neuen Dokumentationsstandard
+
+## Implementierungsplan
+
+### Phase 1: Vorbereitung (1 Woche)
+
+1. Erstellung der neuen Ordnerstruktur
+2. Entwicklung von Dokumentationsvorlagen für verschiedene Dokumenttypen
+3. Identifizierung und Bewertung wertvoller Inhalte aus der bestehenden Dokumentation
+
+### Phase 2: Migration und Erstellung (2-3 Wochen)
+
+1. Migration wertvoller Inhalte in die neue Struktur
+2. Erstellung neuer Dokumentation für unzureichend dokumentierte Komponenten
+3. Aktualisierung der Tracking-Dokumente (features.md, tasks.md)
+
+### Phase 3: Qualitätssicherung und Finalisierung (1 Woche)
+
+1. Überprüfung aller Dokumente auf Konsistenz und Korrektheit
+2. Validierung aller Links und Verweise
+3. Finalisierung der Dokumentation und Veröffentlichung
+
+## Alternative: Inkrementelle Refaktorisierung
+
+Als Alternative zur vollständigen Ersetzung könnte eine inkrementelle Refaktorisierung in Betracht gezogen werden:
+
+### Vorteile:
+
+- Geringeres Risiko von Informationsverlust
+- Kontinuierliche Verfügbarkeit der Dokumentation während der Umstellung
+- Möglichkeit, Ressourcen auf die wichtigsten Bereiche zu konzentrieren
+
+### Nachteile:
+
+- Längerer Zeitraum mit inkonsistenter Dokumentation
+- Höherer Koordinationsaufwand
+- Risiko der Beibehaltung veralteter Strukturen und Formate
+- Schwierigere Durchsetzung neuer Standards
+
+## Fazit
+
+Die vollständige Ersetzung des `docs`-Ordners mit einer sorgfältigen Migration wertvoller Inhalte bietet die beste Lösung für die identifizierten Probleme. Dieser Ansatz ermöglicht einen klaren Neuanfang mit einer konsistenten, gut organisierten Dokumentationsstruktur, während gleichzeitig wertvolle bestehende Inhalte erhalten bleiben.
+
+Die vorgeschlagene neue Struktur bietet eine logische Organisation, die die Auffindbarkeit verbessert und die zukünftige Wartung erleichtert. Der dreiphasige Implementierungsplan stellt sicher, dass der Übergang methodisch und gründlich erfolgt, mit angemessener Aufmerksamkeit für Qualitätssicherung und Konsistenz.
+
+Diese Empfehlung ergänzt den bereits erstellten Dokumentations-Aktualisierungsvorschlag und bietet eine konkrete Antwort auf die Frage, ob der vorhandene `docs`-Ordner ersetzt werden sollte.

docs/planning/documentation-update-proposal.md

@@ -0,0 +1,138 @@
+# Dokumentations-Aktualisierungsvorschlag
+
+## Zusammenfassung
+
+Basierend auf einer umfassenden Analyse des aktuellen Dokumentationsstatus im Projekt schlage ich einen strukturierten Ansatz zur Aktualisierung und Verbesserung der Dokumentation vor. Dieser Vorschlag zielt darauf ab, die in `next-steps.md` und `plan.md` identifizierten Dokumentationslücken zu schließen und einen konsistenten, umfassenden Dokumentationsstandard im gesamten Projekt zu etablieren.
+
+## Aktuelle Situation
+
+Die Analyse hat folgende Punkte ergeben:
+
+1. **Inkonsistente Dokumentationsabdeckung**: Einige Komponenten (wie Analytics) verfügen über umfassende und aktuelle Dokumentation, während andere (wie WAF) trotz Implementierung kaum oder gar nicht dokumentiert sind.
+
+2. **Veraltete Tracking-Dokumente**: Die Tracking-Dokumente (`features.md` und `tasks.md`) spiegeln nicht den tatsächlichen Implementierungsstatus wider. Viele Features und Tasks sind als nicht implementiert markiert, obwohl sie bereits umgesetzt wurden.
+
+3. **Unvollständige technische Dokumentation**: Die API-Dokumentation und Entwickleranleitungen sind unvollständig oder fehlen für viele Komponenten.
+
+4. **Fehlende Inline-Dokumentation**: Viele Klassen und Methoden haben keine oder unzureichende PHPDoc-Kommentare.
+
+5. **Fehlende Automatisierung**: Es gibt keinen automatisierten Prozess, um die Dokumentation aktuell zu halten.
+
+## Vorgeschlagene Maßnahmen
+
+### 1. Aktualisierung der Tracking-Dokumente
+
+- **Aktualisierung von `features.md`**:
+  - Überprüfung jedes Features und Aktualisierung des Implementierungsstatus
+  - Hinzufügen von Links zur entsprechenden Dokumentation für implementierte Features
+  - Ergänzung mit Implementierungsdetails und Nutzungsbeispielen
+
+- **Aktualisierung von `tasks.md`**:
+  - Markierung abgeschlossener Aufgaben
+  - Hinzufügen von Verweisen auf die entsprechenden Pull Requests oder Commits
+  - Ergänzung mit Informationen zum Implementierungsansatz
+
+### 2. Vervollständigung der Komponentendokumentation
+
+- **Standardisierte Dokumentationsstruktur** für jede Komponente mit folgenden Abschnitten:
+  - Übersicht und Zweck
+  - Hauptkomponenten und Klassen
+  - Nutzungsbeispiele
+  - Konfigurationsoptionen
+  - Integration mit anderen Komponenten
+  - Fehlerbehebung
+
+- **Priorisierte Dokumentation** für folgende Komponenten:
+  1. **WAF und Machine Learning**: Vollständige Dokumentation der WAF-Komponente mit Fokus auf:
+     - Architektur und Datenfluss
+     - Feature-Extraktion und Anomalie-Erkennung
+     - Konfiguration und Anpassung
+     - Feedback-System (sobald implementiert)
+  
+  2. **Validation Framework**: Umfassende Dokumentation mit:
+     - Überblick über das Validierungssystem
+     - Verfügbare Validierungsregeln
+     - Erstellung benutzerdefinierter Validierungsregeln
+     - Integration in Formulare und API-Endpunkte
+
+  3. **Security Features**: Dokumentation der Sicherheitsfeatures:
+     - CSRF-Schutz
+     - XSS-Filtierung
+     - Content Security Policy
+     - Authentifizierung und Autorisierung
+
+### 3. Verbesserung der Code-Dokumentation
+
+- **PHPDoc-Standards** für alle Klassen und Methoden:
+  - Beschreibung der Funktionalität
+  - Parameter und Rückgabewerte
+  - Ausnahmen und Fehlerbehandlung
+  - Nutzungsbeispiele für komplexe Methoden
+
+- **Inline-Kommentare** für komplexe Algorithmen und Geschäftslogik
+
+- **Architektur-Diagramme** für komplexe Komponenten und deren Interaktionen
+
+### 4. Entwicklung von Entwickleranleitungen
+
+- **Onboarding-Dokumentation** für neue Entwickler:
+  - Projektstruktur und Architektur
+  - Entwicklungsumgebung einrichten
+  - Coding-Standards und Best Practices
+  - Pull-Request-Prozess
+
+- **Komponenten-Tutorials** mit schrittweisen Anleitungen:
+  - Wie man eine neue Route hinzufügt
+  - Wie man einen neuen Controller erstellt
+  - Wie man mit dem Validierungssystem arbeitet
+  - Wie man die WAF-Komponente konfiguriert
+
+### 5. Automatisierung der Dokumentationspflege
+
+- **Integration in den CI/CD-Prozess**:
+  - Automatische Generierung der API-Dokumentation aus PHPDoc-Kommentaren
+  - Validierung der Dokumentationsvollständigkeit
+  - Warnung bei fehlender Dokumentation für neue Funktionen
+
+- **Dokumentations-Checkliste** für Pull Requests:
+  - Aktualisierung der relevanten Dokumentation
+  - Hinzufügen von PHPDoc-Kommentaren
+  - Aktualisierung der Tracking-Dokumente
+
+- **Automatisierte Statusberichte** zur Dokumentationsabdeckung:
+  - Prozentsatz der dokumentierten Klassen und Methoden
+  - Liste der Komponenten ohne ausreichende Dokumentation
+  - Trend der Dokumentationsabdeckung über Zeit
+
+## Implementierungsplan
+
+### Phase 1: Grundlegende Aktualisierung (1-2 Wochen)
+
+1. Aktualisierung von `features.md` und `tasks.md`
+2. Erstellung von Dokumentationsvorlagen für Komponenten
+3. Dokumentation der WAF-Komponente als Pilotprojekt
+
+### Phase 2: Umfassende Dokumentation (2-4 Wochen)
+
+1. Dokumentation der priorisierten Komponenten
+2. Hinzufügen von PHPDoc-Kommentaren zu Kernklassen
+3. Erstellung von Entwickleranleitungen für häufige Aufgaben
+
+### Phase 3: Automatisierung und Wartung (2-3 Wochen)
+
+1. Implementierung der Dokumentationsautomatisierung
+2. Integration in den CI/CD-Prozess
+3. Erstellung von Dokumentations-Wartungsprozessen
+
+## Erfolgsmetriken
+
+- **Dokumentationsabdeckung**: Prozentsatz der dokumentierten Komponenten und Klassen
+- **Aktualität**: Übereinstimmung zwischen Dokumentation und tatsächlicher Implementierung
+- **Nutzbarkeit**: Feedback von Entwicklern zur Nützlichkeit der Dokumentation
+- **Wartbarkeit**: Zeit, die für die Aktualisierung der Dokumentation benötigt wird
+
+## Fazit
+
+Eine umfassende und aktuelle Dokumentation ist entscheidend für die langfristige Wartbarkeit und Erweiterbarkeit des Projekts. Durch die Umsetzung dieses Vorschlags wird nicht nur die aktuelle Dokumentationslücke geschlossen, sondern auch ein nachhaltiger Prozess etabliert, der sicherstellt, dass die Dokumentation mit der Codebase Schritt hält.
+
+Die vorgeschlagenen Maßnahmen berücksichtigen sowohl die unmittelbaren Bedürfnisse (Aktualisierung der Tracking-Dokumente und Dokumentation wichtiger Komponenten) als auch langfristige Ziele (Automatisierung und Wartungsprozesse). Dies wird zu einer verbesserten Entwicklererfahrung, schnellerer Einarbeitung neuer Teammitglieder und insgesamt höherer Codequalität führen.