# Analytics-Framework: Architektur

## Überblick

Das Analytics-Framework verwendet eine Schichtenarchitektur mit klaren Verantwortlichkeiten:

```
┌─────────────────────────────────────────────────────┐
│                 Öffentliche API                      │
│                  (Analytics)                         │
└───────────────────────┬─────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────┐
│              Event-Verarbeitung                      │
│             (AnalyticsManager)                       │
└───────────────────────┬─────────────────────────────┘
                        │
         ┌──────────────┴──────────────┐
         │                             │
┌────────▼─────────┐         ┌─────────▼────────┐
│   Middleware     │         │  Storage-Layer   │
│   (Pipeline)     │         │ (StorageInterface)│
└──────────────────┘         └──────────────────┘
```

## Komponenten im Detail

### Analytics (Frontend)

Bietet eine benutzerfreundliche API für Tracking-Operationen. Diese Klasse ist der primäre Einstiegspunkt für Anwendungscode und abstrahiert die Komplexität der Eventverarbeitung.

Verantwortlichkeiten:
- Bereitstellung der öffentlichen API (`track`, `page`, `user`, `error`)
- Integration mit dem Event-Dispatcher des Frameworks
- Typ-Konvertierung zwischen benutzerdefinierten Ereignissen und dem internen Datenformat

### AnalyticsManager (Verarbeitung)

Der Manager ist das Herzstück des Systems und verantwortlich für:
- Anwendung von Middleware-Transformationen auf Events
- Eventpufferung für effiziente Speicherung
- Verwaltung der Konfiguration
- Steuerung des Storage-Layers

Der Manager implementiert einen Event-Buffer, der Daten sammelt und bei Erreichen einer konfigurierbaren Größe automatisch speichert.

### Middleware-System

Eine Kette von Verarbeitungsfunktionen, die auf jedes Event angewendet werden:
- Datenfilterung und -transformation
- Anonymisierung persönlicher Daten
- Validierung und Anreicherung von Events

Jede Middleware kann Events modifizieren oder komplett verwerfen.

### Storage-Layer

Abstraktion für verschiedene Speichermethoden durch das `StorageInterface`:

```php
interface StorageInterface
{
    public function store(array $events): void;
    public function retrieve(array $filters = []): array;
    public function clear(): void;
}
```

Implementierungen:
- `FileStorage`: Speichert Events in JSON-Dateien mit täglicher Rotation
- Erweiterbar für andere Backends (Datenbank, Redis, etc.)

### HTTP-Integration

`AnalyticsMiddleware` integriert Analytics in den HTTP-Request-Lifecycle:
- Tracking von eingehenden Requests
- Erfassung von Antwortzeiten und Statuscodes
- Fehlererfassung bei Exceptions

### Admin-Dashboard

`AnalyticsDashboard` und `AdminAnalyticsController` bieten:
- Datenaggregation und -analyse
- Visualisierung von Metriken
- Filterung nach Zeiträumen
- Verschiedene spezialisierte Ansichten (Seiten, Fehler, Performance)

## Datenfluss

1. Event wird durch `Analytics::track()` oder ähnliche Methoden erstellt
2. `AnalyticsManager` wendet Middleware-Pipeline an
3. Event wird zum Buffer hinzugefügt
4. Bei Buffer-Füllung oder explizitem `flush()` werden Events an Storage übergeben
5. Storage speichert Events im konfigurierten Backend
6. `AnalyticsDashboard` ruft Daten bei Bedarf vom Storage ab und aggregiert sie

## Erweiterungspunkte

- **Storage-Provider**: Neue Implementierungen von `StorageInterface`
- **Middleware**: Funktionen für Filterung/Transformation
- **Event-Typen**: Spezialisierte Event-Klassen für typsicheres Tracking
- **Dashboard-Views**: Zusätzliche Visualisierungen und Berichte