fix: Gitea Traefik routing and connection pool optimization

- Remove middleware reference from Gitea Traefik labels (caused routing issues) - Optimize Gitea connection pool settings (MAX_IDLE_CONNS=30, authentication_timeout=180s) - Add explicit service reference in Traefik labels - Fix intermittent 504 timeouts by improving PostgreSQL connection handling Fixes Gitea unreachability via git.michaelschiemer.de
2025-11-09 14:46:15 +01:00
parent 85c369e846
commit 36ef2a1e2c
1366 changed files with 104925 additions and 28719 deletions
--- a/docs/planning/ADMIN_AUTH_SECURITY_ENHANCEMENT.md
+++ b/docs/planning/ADMIN_AUTH_SECURITY_ENHANCEMENT.md
@@ -0,0 +1,140 @@
+# Admin Auth Security Enhancement Plan
+
+**Status**: Geplant für später (nach Refactoring anderer Module)  
+**Ansatz**: Starke Web-Authentifizierung ohne VPN
+
+## Überblick
+
+Erweitert das Auth-Modul für den Admin-Bereich mit mehrschichtiger Web-Authentifizierung. Fokus auf starke Authentifizierung mit MFA, Session-Sicherheit und Rate Limiting.
+
+## Sicherheitsebenen
+
+1. **Obligatorisches MFA (TOTP)** - Zweiter Faktor zwingend erforderlich
+2. **Strenge Session-Sicherheit** - Regeneration, IP-Tracking, Timeouts
+3. **Rate Limiting & Account Lockout** - Schutz gegen Brute-Force
+4. **IP-basierte Einschränkungen** (optional) - Zusätzliche Barriere ohne VPN
+5. **Security Headers** - CSRF-Schutz, Secure Cookies, HSTS
+
+## Aktuelle Situation
+
+- Basis-Authentifizierung mit Session-Management vorhanden
+- MFA/TOTP-Services existieren (`TotpService`, `MfaService`), aber nicht vollständig integriert
+- IP-basierte Einschränkungen existieren (`ProductionSecurityMiddleware`)
+- AuthMiddleware ist derzeit deaktiviert
+- RouteAuthorizationService existiert, aber nicht konfiguriert
+
+## Implementation Plan
+
+### Phase 1: Auth-Modul Erweiterung
+
+1. **AdminAuthService** erstellen
+   - Integration mit bestehendem `AuthenticationService`
+   - Admin-spezifische Authentifizierungslogik
+   - Session-Management für Admin-Bereich
+   - IP-Tracking und Session-Regeneration
+   - MFA-Status-Prüfung
+
+2. **MFA-Integration** für Admin-Bereich
+   - TOTP als obligatorische zweite Faktor über `MfaService`/`TotpProvider`
+   - QR-Code-Generierung für Setup
+   - Backup-Codes für Recovery
+   - MFA-Enforcement für alle Admin-Routen
+
+3. **Session-Sicherheit** verbessern
+   - Session-Regeneration bei Login
+   - IP-Konsistenz-Prüfung (warnen bei IP-Wechsel)
+   - Session-Timeouts für Admin-Bereich (kürzer als normale Sessions)
+   - Session-Fixation-Schutz
+   - Secure Cookie-Flags (HttpOnly, Secure, SameSite)
+
+### Phase 2: Route Protection & Authorization
+
+1. **RouteAuthorizationService** aktivieren und konfigurieren
+   - Admin-Namespace (`App\Application\Admin\*`) konfigurieren
+   - IP-basierte Zugriffskontrolle (optional, aber empfohlen)
+   - MFA-Status-Prüfung für alle Admin-Routen
+
+2. **AuthMiddleware** implementieren
+   - Integration mit `RouteAuthorizationService`
+   - Session-Validierung
+   - MFA-Status-Prüfung
+   - Redirect zu Login bei fehlender Authentifizierung
+   - Redirect zu MFA-Setup bei fehlender MFA-Konfiguration
+
+3. **AdminLoginController** erstellen
+   - Login-Formular
+   - MFA-Setup-Flow (wenn noch nicht konfiguriert)
+   - MFA-Verifizierung nach initialem Login
+   - Session-Erstellung
+   - Logout-Funktionalität
+
+### Phase 3: Erweiterte Sicherheitsfeatures
+
+1. **IP-basierte Einschränkungen** (Optional, aber empfohlen)
+   - Statische IP-Whitelist für Admin-Zugriff
+   - CIDR-Notation für IP-Ranges unterstützen
+   - Konfigurierbar über Environment-Variablen
+   - Integration mit `ProductionSecurityMiddleware`
+
+2. **Rate Limiting** für Admin-Bereich
+   - Striktere Limits als für normale User
+   - IP-basierte Rate Limits
+   - Account-Lockout nach fehlgeschlagenen Versuchen
+   - Separate Limits für Login, MFA-Verifizierung
+
+3. **Security Headers**
+   - CSRF-Schutz für alle Admin-Formulare
+   - Secure Cookies (HTTPS-only)
+   - HSTS für Admin-Bereich
+   - Content-Security-Policy
+
+## Dateien die erstellt/geändert werden müssen
+
+### Neue Dateien
+- `src/Framework/Auth/AdminAuthService.php` - Admin-spezifischer Auth-Service
+- `src/Application/Admin/Auth/AdminLoginController.php` - Login-Controller
+- `src/Framework/Auth/MfaRequiredException.php` - Exception für fehlende MFA
+- `src/Framework/Auth/AdminMfaService.php` - MFA-Service für Admin-Bereich
+- `src/Framework/Auth/AdminMfaSetupResult.php` - Result Value Objects
+- `src/Framework/Auth/AdminMfaActivationResult.php`
+- `src/Framework/Auth/AdminMfaVerificationResult.php`
+- `tests/Framework/Auth/AdminAuthServiceTest.php` - Tests
+- `tests/Framework/Auth/AdminMfaServiceTest.php` - MFA-Tests
+
+### Zu erweiternde Dateien
+- `src/Framework/Http/Middlewares/AuthMiddleware.php` - Vollständige Implementierung
+- `src/Framework/Auth/RouteAuthorizationServiceInitializer.php` - Konfiguration aktivieren
+- `src/Framework/Auth/AuthenticationService.php` - MFA-Integration
+- `src/Framework/Http/Middlewares/ProductionSecurityMiddleware.php` - IP-Whitelist-Erweiterung
+- `src/Framework/Config/EnvKey.php` - Environment-Keys hinzufügen
+
+## Konfiguration
+
+### Environment-Variablen
+- `ADMIN_MFA_REQUIRED=true` - MFA obligatorisch
+- `ADMIN_SESSION_TIMEOUT=1800` - Session-Timeout (30 Min)
+- `ADMIN_IP_WHITELIST` - Optionale IP-Whitelist (komma-separiert, CIDR unterstützt)
+- `ADMIN_RATE_LIMIT_ATTEMPTS=3` - Strikte Rate Limits
+- `ADMIN_ACCOUNT_LOCKOUT_DURATION=3600` - Lockout nach Fehlversuchen (1h)
+- `ADMIN_SESSION_REGENERATE_ON_LOGIN=true` - Session-Regeneration
+- `ADMIN_CHECK_IP_CONSISTENCY=true` - IP-Wechsel überwachen
+
+### MFA-Integration
+- Verwende `MfaService` mit `TotpProvider` (nicht direkt `TotpService`)
+- `MfaMethod::TOTP` für TOTP-Authentifizierung
+- `MfaSecret`, `MfaChallenge`, `MfaCode` Value Objects verwenden
+
+## Wichtige Hinweise
+
+- **Kein VPN**: Lösung basiert auf starker Web-Authentifizierung ohne VPN
+- **MFA obligatorisch**: Alle Admin-Routen erfordern konfigurierte und verifizierte MFA
+- **Audit-Logging**: Wird später implementiert, wenn eine vollständige Audit-Lösung im Framework vorhanden ist
+- **IP-Whitelist**: Optional, aber empfohlen für Production
+
+## Referenzen
+
+- MFA-Modul: `src/Framework/Mfa/`
+- TotpProvider: `src/Framework/Mfa/Providers/TotpProvider.php`
+- RouteAuthorizationService: `src/Framework/Auth/RouteAuthorizationService.php`
+- ProductionSecurityMiddleware: `src/Framework/Http/Middlewares/ProductionSecurityMiddleware.php`
+
--- a/docs/planning/CLEANUP_PLAN.md
+++ b/docs/planning/CLEANUP_PLAN.md
@@ -0,0 +1,186 @@
+# Root Directory Cleanup Plan
+
+## 1. Files to Move
+
+### Debug Scripts → scripts/debug/
+```bash
+mv debug_*.php scripts/debug/
+mv test_*.php scripts/test/
+mv simple_debug_tui.php scripts/debug/
+mv populate_images_from_filesystem.php scripts/maintenance/
+mv websocket.php scripts/test/
+```
+
+### Documentation → docs/
+```bash
+# Root markdown files to consolidate
+mv AUTOLOADER_WORKAROUND.md docs/troubleshooting/
+mv DEPLOYMENT*.md docs/deployment/
+mv SSL-PRODUCTION-SETUP.md docs/deployment/
+mv PRODUCTION-SECURITY-UPDATES.md docs/deployment/
+mv README-*.md docs/guides/
+mv TODO.md docs/
+mv docs-*.md docs/planning/
+```
+
+### Public Directory Security Cleanup
+```bash
+# REMOVE from public/ (move to scripts/debug/)
+mv public/debug.php scripts/debug/
+mv public/test.php scripts/test/
+mv public/security-test.php scripts/debug/
+mv public/production-test.php scripts/debug/
+mv public/quick-fix.php scripts/debug/
+mv public/build-container.php scripts/debug/
+mv public/force-production-test.php scripts/debug/
+mv public/dev-hot-reload*.php scripts/debug/
+mv public/minimal.php scripts/debug/
+
+# public/ should only contain:
+# - index.php (production entry point)
+# - health.php (monitoring)
+# - .vite/ (build artifacts)
+# - assets/ (compiled assets)
+```
+
+## 2. New Directory Structure
+
+```
+michaelschiemer/
+├── bin/                          # Executable scripts
+│   ├── console                   # Symlink to console.php
+│   └── worker                    # Symlink to worker.php
+├── config/                       # Configuration files
+│   └── static-routes.json
+├── docs/                         # Consolidated documentation
+│   ├── README.md
+│   ├── architecture/
+│   │   ├── framework-principles.md
+│   │   ├── di-container.md
+│   │   └── discovery-system.md
+│   ├── deployment/
+│   │   ├── production-setup.md
+│   │   ├── ssl-configuration.md
+│   │   └── docker-guide.md
+│   ├── guides/
+│   │   ├── getting-started.md
+│   │   ├── api-versioning.md
+│   │   └── testing.md
+│   ├── troubleshooting/
+│   │   ├── autoloader-workaround.md
+│   │   └── common-issues.md
+│   └── planning/
+│       └── TODO.md
+├── public/                       # Web-accessible (MINIMAL!)
+│   ├── index.php
+│   ├── health.php
+│   └── .vite/
+├── resources/                    # Source assets
+│   ├── css/
+│   └── js/
+├── scripts/                      # Development & maintenance
+│   ├── debug/                   # Debug scripts (NOT web-accessible)
+│   ├── test/                    # Test scripts
+│   ├── deployment/              # Deployment scripts
+│   └── maintenance/             # Maintenance scripts
+├── src/                         # Application source
+├── storage/                     # Runtime data
+│   ├── cache/                   # Add to .gitignore
+│   ├── logs/
+│   └── uploads/
+├── tests/                       # Test suite
+├── vendor/                      # Composer dependencies
+└── var/                         # Temporary files
+    └── phpstan/cache/           # Add to .gitignore
+```
+
+## 3. Gitignore Updates
+
+Add to `.gitignore`:
+```
+# Cache
+storage/cache/*.cache.php
+storage/cache/*.php
+
+# PHPStan
+var/phpstan/cache/**
+
+# Logs
+storage/logs/*.log
+
+# Temporary debug files
+scripts/debug/output/
+scripts/test/output/
+```
+
+## 4. Immediate Actions
+
+### Priority 1: Security (DO IMMEDIATELY!)
+```bash
+# Remove debug files from public/
+rm public/debug.php
+rm public/test.php
+rm public/security-test.php
+rm public/production-test.php
+rm public/quick-fix.php
+rm public/build-container.php
+rm public/force-production-test.php
+rm public/dev-hot-reload.php
+rm public/dev-hot-reload-minimal.php
+rm public/minimal.php
+```
+
+### Priority 2: Cache Cleanup
+```bash
+# Clear old cache files
+find storage/cache -name "*.cache.php" -mtime +7 -delete
+find var/phpstan/cache -type f -mtime +7 -delete
+```
+
+### Priority 3: Documentation Consolidation
+```bash
+# Create new structure
+mkdir -p docs/{architecture,deployment,guides,troubleshooting,planning}
+mkdir -p scripts/{debug,test,deployment,maintenance}
+
+# Move files (execute moves from section 1)
+```
+
+## 5. Benefits
+
+- ✅ **Security**: No debug code in public/
+- ✅ **Organization**: Clear separation of concerns
+- ✅ **Performance**: Cleaner cache structure
+- ✅ **Developer Experience**: Easy navigation
+- ✅ **Professional**: Clean root directory
+- ✅ **Maintainability**: Consolidated documentation
+
+## 6. Automated Cleanup Script
+
+Create `scripts/maintenance/cleanup-project.php`:
+```php
+#!/usr/bin/env php
+<?php
+// Automated cleanup script
+// - Clear old cache files
+// - Remove temporary files
+// - Validate directory structure
+```
+
+## Execution Timeline
+
+**Week 1**:
+- Security cleanup (public/ directory)
+- Cache cleanup
+
+**Week 2**:
+- Documentation consolidation
+- Root directory organization
+
+**Week 3**:
+- Script organization
+- Automated cleanup tools
+
+**Week 4**:
+- Validation & testing
+- Update documentation
--- a/docs/planning/LIVECOMPONENTS_TEST.md
+++ b/docs/planning/LIVECOMPONENTS_TEST.md
@@ -0,0 +1,160 @@
+# 🧪 LiveComponents Test Guide
+
+## Quick Test
+
+1. **Start Server**:
+   ```bash
+   make up
+   npm run dev
+   ```
+
+2. **Open Test Page**:
+   ```
+   https://localhost/test/livecomponents
+   ```
+
+3. **Test Counter Component**:
+   - ✅ Click **+ Increment** → Count increases
+   - ✅ Click **- Decrement** → Count decreases
+   - ✅ Click **Reset** → Count resets to 0
+   - ✅ Enter **5** and click **Add Amount** → Count +5
+   - ✅ Wait 10 seconds → Auto-update (polling)
+
+## What's Being Tested
+
+### ✅ Core Features
+- **Action Handling** - Button clicks execute component methods
+- **Form Submission** - Forms with parameters work
+- **State Management** - Component data persists and updates
+- **Polling** - Auto-updates every 10 seconds
+- **DOM Updates** - HTML re-renders on state change
+
+### ✅ Framework Patterns
+- **Trait + Interface** - No abstract classes
+- **Readonly Classes** - Immutable components
+- **Value Objects** - Type-safe data handling
+- **Dependency Injection** - TemplateRenderer injection
+
+### ✅ JavaScript
+- **Zero Dependencies** - Pure Vanilla JS
+- **Auto-initialization** - Finds components on page load
+- **Event Handling** - Buttons, forms, polling
+- **Progress Tracking** - Upload progress (ready for file uploads)
+
+## Test Files
+
+```
+src/
+├── Application/
+│   ├── Controllers/Test/
+│   │   ├── LiveComponentTestController.php  ← Test Route
+│   │   └── README.md                        ← Test Documentation
+│   └── Components/
+│       └── CounterComponent.php             ← Test Component
+├── Framework/LiveComponents/
+│   └── Templates/
+│       └── counter.view.php                 ← Component Template
+└── resources/views/test/
+    └── livecomponents.view.php             ← Test Page
+```
+
+## Browser Console Output
+
+Expected console output:
+```javascript
+LiveComponents Test Suite Loaded
+Available: {
+  liveComponents: LiveComponentManager,
+  sseManager: SSEManager
+}
+```
+
+## Network Requests
+
+Watch for:
+```
+POST /live-component/App\Application\Components\CounterComponent:demo
+
+Request:
+{
+  "component_id": "App\\Application\\Components\\CounterComponent:demo",
+  "method": "increment",
+  "params": {},
+  "state": { "count": 0 }
+}
+
+Response:
+{
+  "html": "<div>...</div>",
+  "events": [],
+  "state": "{\"id\":\"...\",\"component\":\"...\",\"data\":{\"count\":1}}"
+}
+```
+
+## Debugging
+
+### ❌ Component not initializing?
+```javascript
+// Check if LiveComponents loaded
+console.log(window.liveComponents);
+
+// Check component registered
+console.log(window.liveComponents.components);
+```
+
+### ❌ Actions not working?
+```javascript
+// Manual action call
+window.liveComponents.callAction(
+  'App\\Application\\Components\\CounterComponent:demo',
+  'increment',
+  {}
+);
+```
+
+### ❌ Polling not working?
+```javascript
+// Check polling interval
+document.querySelector('[data-poll-interval]').dataset.pollInterval;
+
+// Force poll
+window.liveComponents.callAction('CounterComponent:demo', 'poll', {});
+```
+
+## Next: Add Your Own Component
+
+```php
+// 1. Create Component
+final readonly class MyComponent implements LiveComponentContract
+{
+    use LiveComponentTrait;
+
+    public function __construct(string $id, array $initialData = [], ?TemplateRenderer $templateRenderer = null) {
+        $this->id = $id;
+        $this->initialData = $initialData;
+        $this->templateRenderer = $templateRenderer;
+    }
+
+    public function render(): string {
+        return $this->template('Framework/LiveComponents/Templates/my-component', []);
+    }
+
+    public function myAction(): array {
+        return ['updated' => true];
+    }
+}
+
+// 2. Add to LiveComponentTestController
+$myComponent = new MyComponent(
+    id: ComponentRegistry::makeId(MyComponent::class, 'test')
+);
+
+// 3. Render in view
+{!! myComponent.toHtml() !!}
+```
+
+## Documentation
+
+- 📚 Full docs: `/docs/claude/livecomponents-system.md`
+- 📦 Module README: `/src/Framework/LiveComponents/README.md`
+- 🧪 Test README: `/src/Application/Controllers/Test/README.md`
--- a/docs/planning/SRC_STRUCTURE_IMPROVEMENTS.md
+++ b/docs/planning/SRC_STRUCTURE_IMPROVEMENTS.md
@@ -0,0 +1,368 @@
+# Src Directory Structure Improvements
+
+## Current Issues
+
+### 1. Application Layer Fragmentation
+```
+src/Application/
+├── Admin/              # Admin features
+├── Api/                # API endpoints
+├── Auth/               # Authentication
+├── Backend/            # Backend integrations?
+├── Campaign/           # Campaign management
+├── Controller/         # Generic controllers?
+├── Design/             # Design system?
+├── Http/               # HTTP utilities
+├── Service/            # Generic services?
+├── Website/            # Website pages
+└── ... (20+ directories)
+```
+
+**Problem**:
+- No clear separation between features and infrastructure
+- Mix of feature modules and technical layers
+- Hard to find related code
+
+### 2. Framework Layer Organization
+```
+src/Framework/
+├── Async/
+├── AsyncExamples/      # Examples should not be in Framework/
+├── Cache/
+├── Database/
+├── DI/
+├── Discovery/
+└── ... (50+ directories)
+```
+
+**Problem**:
+- Examples mixed with production code
+- Very deep nesting (Database/Schema/Index/Analysis/)
+- Some modules could be consolidated
+
+### 3. Domain Layer Inconsistency
+```
+src/Domain/
+├── AI/                 # Is this really domain?
+├── Common/             # Shared code
+├── Contact/
+├── Media/
+├── Meta/               # What is Meta domain?
+├── Newsletter/
+├── PreSave/            # Feature-specific
+├── SmartLink/
+└── User/
+```
+
+**Problem**:
+- Mix of bounded contexts and shared code
+- Unclear domain boundaries
+- Technical concerns (AI) mixed with business domains
+
+## Proposed Improvements
+
+### A. Application Layer Restructuring
+
+**Option 1: Feature-Based Modules** (RECOMMENDED)
+```
+src/Application/
+├── Admin/                          # Admin Panel Feature
+│   ├── Analytics/
+│   ├── Content/
+│   ├── System/
+│   └── Controllers/
+├── Api/                            # API Layer
+│   ├── V1/
+│   ├── V2/
+│   └── Middleware/
+├── Auth/                           # Authentication Feature
+│   ├── Controllers/
+│   ├── Middleware/
+│   └── Services/
+├── Campaign/                       # Campaign Management Feature
+│   ├── Controllers/
+│   ├── Services/
+│   └── ValueObjects/
+├── Website/                        # Public Website Feature
+│   ├── Controllers/
+│   ├── Services/
+│   └── templates/
+└── Shared/                         # Application-wide shared code
+    ├── Controllers/                # Base controllers
+    ├── Middleware/
+    └── Services/
+```
+
+**Benefits**:
+- Clear feature boundaries
+- Related code grouped together
+- Easy to find and navigate
+- Follows Vertical Slice Architecture
+
+**Option 2: Layer-Based Organization**
+```
+src/Application/
+├── Controllers/                    # All controllers
+│   ├── Admin/
+│   ├── Api/
+│   ├── Auth/
+│   └── Website/
+├── Services/                       # All services
+├── Middleware/                     # All middleware
+└── ValueObjects/                   # Application VOs
+```
+
+**Benefits**:
+- Technical separation
+- Easy to see all controllers/services
+- Simpler structure
+
+**Downside**: Harder to see complete features
+
+### B. Framework Layer Improvements
+
+**Clean Up Examples**:
+```bash
+# Move examples OUT of src/Framework/
+src/
+├── Framework/                      # Production framework code
+│   ├── Cache/
+│   ├── Database/
+│   ├── DI/
+│   └── ...
+└── Examples/                       # All examples here
+    ├── Async/
+    ├── Cache/
+    ├── Database/
+    └── GraphQL/
+```
+
+**Consolidate Deep Nesting**:
+```
+src/Framework/Database/
+├── Connection/                     # Consolidated connection handling
+│   ├── Async/
+│   ├── Middleware/
+│   ├── Pooled/
+│   └── ReadWrite/
+├── Migration/
+│   ├── Commands/
+│   ├── Runners/
+│   └── ValueObjects/
+├── Monitoring/
+│   ├── Health/
+│   ├── Profiling/
+│   └── Metrics/
+├── QueryBuilder/
+├── Repository/
+├── Schema/
+│   ├── Blueprint/
+│   ├── Comparison/
+│   └── Index/
+└── UnitOfWork/
+```
+
+**Instead of**:
+```
+Database/
+  Monitoring/
+    Health/
+      Checks/                       # Too deep!
+```
+
+### C. Domain Layer Restructuring
+
+**Bounded Contexts Approach**:
+```
+src/Domain/
+├── BoundedContexts/                # Clear business domains
+│   ├── Campaign/
+│   │   ├── Entities/
+│   │   ├── ValueObjects/
+│   │   ├── Services/
+│   │   └── Repositories/
+│   ├── Contact/
+│   ├── Media/
+│   ├── Newsletter/
+│   ├── SmartLink/                  # Renamed from PreSave
+│   └── User/
+├── Shared/                         # Shared Kernel
+│   ├── ValueObjects/               # Cross-domain VOs
+│   ├── Interfaces/
+│   └── Exceptions/
+└── Services/                       # Domain Services
+    └── AI/                         # AI as domain service
+```
+
+**Benefits**:
+- Clear bounded context boundaries
+- Shared kernel explicit
+- Domain services separated
+- DDD-compliant structure
+
+## Migration Strategy
+
+### Phase 1: Immediate Cleanup (Week 1)
+```bash
+# 1. Move examples out of Framework
+mkdir -p examples
+mv src/Framework/AsyncExamples examples/Async
+mv src/Framework/Database/Examples examples/Database
+# ... repeat for all examples
+
+# 2. Update composer.json autoload
+"autoload": {
+    "psr-4": {
+        "App\\": "src/",
+        "Examples\\": "examples/"
+    }
+}
+
+# 3. Regenerate autoloader
+composer dump-autoload
+```
+
+### Phase 2: Documentation (Week 2)
+```bash
+# Create architecture docs
+docs/architecture/
+├── application-layer.md            # Feature-based organization
+├── framework-layer.md              # Framework structure
+├── domain-layer.md                 # Bounded contexts
+└── migration-guide.md              # How to navigate new structure
+```
+
+### Phase 3: Gradual Migration (Weeks 3-6)
+- Move Application code to feature modules (one at a time)
+- Consolidate Framework deep nesting
+- Restructure Domain bounded contexts
+- Update imports and tests
+
+## Recommended Final Structure
+
+```
+michaelschiemer/
+├── bin/
+├── config/
+├── docs/
+│   ├── architecture/
+│   ├── deployment/
+│   └── guides/
+├── examples/                       # All framework examples
+│   ├── Async/
+│   ├── Cache/
+│   ├── Database/
+│   └── GraphQL/
+├── public/                         # Minimal! Only index.php + health.php
+├── resources/
+│   ├── css/
+│   └── js/
+├── scripts/
+│   ├── debug/
+│   ├── test/
+│   ├── deployment/
+│   └── maintenance/
+├── src/
+│   ├── Application/                # Feature-based modules
+│   │   ├── Admin/
+│   │   ├── Api/
+│   │   ├── Auth/
+│   │   ├── Campaign/
+│   │   ├── Website/
+│   │   └── Shared/
+│   ├── Domain/                     # Bounded contexts
+│   │   ├── BoundedContexts/
+│   │   │   ├── Campaign/
+│   │   │   ├── Contact/
+│   │   │   ├── Media/
+│   │   │   ├── Newsletter/
+│   │   │   ├── SmartLink/
+│   │   │   └── User/
+│   │   ├── Shared/
+│   │   └── Services/
+│   ├── Framework/                  # Framework (production only)
+│   │   ├── Cache/
+│   │   ├── Console/
+│   │   ├── Database/
+│   │   ├── DI/
+│   │   ├── Discovery/
+│   │   ├── Http/
+│   │   └── ...
+│   └── Infrastructure/             # External integrations
+│       ├── GeoIp/
+│       └── ...
+├── storage/
+├── tests/                          # Mirrors src/ structure
+│   ├── Application/
+│   ├── Domain/
+│   ├── Framework/
+│   └── Integration/
+├── var/
+└── vendor/
+
+```
+
+## Quality Metrics
+
+**Before**:
+- Root files: 105
+- Public debug files: 9
+- Application directories: 25+
+- Framework nesting depth: 6 levels
+- Examples in production: Yes
+
+**After**:
+- Root files: ~15 (essential only)
+- Public debug files: 0 (SECURITY!)
+- Application modules: ~8 (feature-based)
+- Framework nesting depth: 3-4 levels max
+- Examples location: Separate examples/ directory
+
+## Implementation Checklist
+
+- [ ] Move debug/test scripts to scripts/
+- [ ] Clean up public/ directory (SECURITY PRIORITY!)
+- [ ] Move examples out of src/Framework/
+- [ ] Create examples/ directory
+- [ ] Consolidate documentation in docs/
+- [ ] Restructure Application layer (feature-based)
+- [ ] Simplify Framework deep nesting
+- [ ] Organize Domain bounded contexts
+- [ ] Update composer autoload
+- [ ] Update all imports
+- [ ] Update tests to match new structure
+- [ ] Update .gitignore
+- [ ] Clear old cache files
+- [ ] Document new structure
+- [ ] Create navigation guide
+
+## Tools to Create
+
+### 1. Structure Validator
+```bash
+php console.php structure:validate
+
+# Checks:
+# - No PHP files in public/ except index.php/health.php
+# - All examples in examples/ directory
+# - Cache size warnings
+# - Proper namespace structure
+```
+
+### 2. Automatic Cleanup
+```bash
+php console.php cleanup:project
+
+# Actions:
+# - Clear old cache files
+# - Remove temporary files
+# - Report orphaned files
+```
+
+### 3. Migration Helper
+```bash
+php console.php migrate:structure --dry-run
+
+# Shows what would be moved/changed
+# Then run without --dry-run to execute
+```