Architektur-Übersicht

Postbox ist eine Social-Media-Monitoring-Plattform für Instagram- und YouTube-Profile. Die Anwendung erfasst Follower-Metriken, berechnet Scores, findet ähnliche Profile und stellt Dashboards bereit.

Tech-Stack

Komponente	Technologie
Framework	Laravel 12 (PHP 8.4)
UI	Livewire V3 + Flux UI (Pro)
Datenbank	PostgreSQL
Auth	WorkOS SSO (Laravel WorkOS-Starterkit)
Cache/Queue	Database Driver (Redis optional)
WebSockets	Laravel Reverb
Frontend	Vite, Tailwind CSS 4, Alpine.js, Laravel Echo
Monitoring	Flare, Laravel Pulse, Nightwatch, Vantage
Analytics	Matomo (Server-Side Tracking)
Tests	Pest

Verzeichnisstruktur

postbox/
├── app/
│   ├── Console/Commands/           # 39 Artisan Commands (Scheduled Jobs, Admin-Tools)
│   ├── Events/                     # 11 Broadcast Events + Concerns/
│   ├── Http/
│   │   ├── Controllers/            # 11 Controllers (inkl. Api/, Watchers/)
│   │   ├── Middleware/             # 5 Custom Middleware
│   │   └── Requests/Collector/     # 4 Form Requests fuer Collector API
│   ├── Jobs/                       # 18 Queue Jobs (CrossPlatform/, Instagram/, YouTube/)
│   ├── Livewire/                   # 40 Components (Admin/, Dashboard/, Explore/, ...)
│   ├── Models/                     # 44 Eloquent Models
│   ├── Observers/                  # 2 Observers (User, WatcherSource)
│   ├── Policies/                   # 1 Policy (CollectorJob)
│   ├── Providers/                  # 3 Providers (App, Auth, Volt)
│   ├── Services/                   # 45 Service-Klassen (Business-Logik)
│   └── Support/                    # Hilfsklassen (CurrentWorkspace, HumanNumber, ...)
├── config/
│   ├── postbox.php                 # Zentrale App-Konfiguration
│   ├── collector.php               # Collector-Job-Settings
│   ├── feedback.php                # Feedback-Feature
│   ├── google_api_usage.php        # Google API Quota Monitoring
│   ├── server-monitoring.php       # Server-Alert-Schwellwerte
│   └── vantage.php                 # Vantage Queue Monitoring
├── database/
│   ├── factories/                  # 5 Factories (User, Collector, SocialProfile, ...)
│   ├── migrations/                 # 80+ Migrations
│   └── seeders/                    # 2 Seeders (Database, ExploreCategory)
├── resources/views/
│   ├── components/                 # Blade Components (layouts/, explore/, sidebar/)
│   └── livewire/                   # Livewire Views (admin/, dashboard/, explore/, ...)
├── routes/
│   ├── web.php                     # Haupt-Routen (Public, Auth, Admin)
│   ├── api.php                     # Collector REST API (Sanctum)
│   ├── channels.php                # Broadcast Channel Authorization
│   ├── console.php                 # Schedule + Closures
│   ├── auth.php                    # WorkOS SSO Routes
│   └── settings.php                # Settings-Routen (Profile, Appearance, Notifications)
├── tests/
│   ├── Feature/                    # ~85 Feature Tests
│   └── Unit/                       # ~40 Unit Tests
└── CLAUDE.md                       # Claude Code Instructions

Key Concepts

Konzept	Beschreibung
Workspace	Logische Gruppierung von Watchern. Jeder User kann mehrere Workspaces besitzen. Ein spezieller Admin-Workspace (ID 999999999999) spiegelt alle Profile.
Watcher	Beobachtet ein Social-Media-Profil innerhalb eines Workspaces. Verbindet Workspace mit SocialProfile ueber WatcherSource.
WatcherSource	Verbindungstabelle zwischen Watcher und SocialProfile. Ein Watcher kann mehrere Sources haben (Multi-Platform).
SocialProfile	Zentrales Model fuer Instagram- und YouTube-Profile. Traegt Status-Flags (blocked_at, sanitized_at, deactivated_at, archived_at).
Collector	Externer Scraping-Service (Instagram). Kommuniziert ueber die REST API (/api/collector/). Least Jobs, liefert Ergebnisse zurueck.
CollectorJob	Einzelner Scraping-Auftrag fuer den Collector. Status-Lifecycle: Queued -> Leased -> Completed/Failed.
DailySyncRun	Markiert einen vollstaendigen taeglichen Scrape-Durchlauf. Wird von Explore- und Dashboard-Berechnungen referenziert.
ProfileScore	Bewertung 0-100 pro Profil (Growth 40%, Momentum 30%, Consistency 20%, Engagement 10%). Tier-normalisiert.
ExploreMetric	Taegliche Growth- und Trending-Kennzahlen fuer die Explore-Seite.
Announcement	Geteilte Benachrichtigung (1 Zeile pro Event, Read-Tracking ueber announcement_reads).

Request-Lifecycle

Browser
  └─> Route (web.php / api.php)
        └─> Middleware (SecurityHeaders, Auth, EnsureWorkspace, TrackPageView, ...)
              └─> Livewire Component / Controller
                    └─> Service Layer (app/Services/)
                          └─> Eloquent Model (app/Models/)
                                └─> PostgreSQL

Fuer Echtzeit-Updates laeuft ein paralleler Pfad:

Queue Job / Artisan Command
  └─> Event::dispatch()
        └─> Laravel Reverb (WebSocket)
              └─> Browser (Laravel Echo)
                    └─> Alpine.js / Livewire Handler
                          └─> Flux Toast / NotificationCenter Update

Wichtige Konventionen

Regel	Beschreibung
Deutsche UI-Labels	Alle sichtbaren Texte auf Deutsch, Du-Form ("Hinzufuegen", "Speichern", "Loeschen")
Flux UI	Strikte Nutzung von Flux UI (Pro) Komponenten -- kein React, Vue oder jQuery
Toast statt Flash	$this->dispatch('show-toast', ...) statt session()->flash()
Inline-Kommentare	// Inline comment: bei nicht-offensichtlicher Logik
Zahlenformat	Deutsches Format mit number_format($n, 0, ',', '.')
Seiten-Titel	Immer setzen via ->title() oder Layout-Parameter
Ausschluss-Filter	Bei oeffentlichen Queries immer notExcluded() oder einzelne whereNull-Checks
Event-Dispatch	Keine Named Parameters: MyEvent::dispatch($arg1, $arg2)
Admin-Check	Via $this->authorizeAdmin() oder Gate::allows('admin')
Code-Style	Laravel Pint vor jedem Commit (./vendor/bin/pint)