# Projektstruktur-Dokumentation

## Übersicht

Diese Dokumentation bietet einen Überblick über die Architektur und Struktur des Projekts. Die Anwendung folgt einer modularen, serviceorientierten Architektur mit klarer Trennung von Verantwortlichkeiten.

## Hauptverzeichnisse

### `/src`

Das Hauptverzeichnis für den Anwendungscode, unterteilt in mehrere Unterverzeichnisse:

#### `/src/Framework`

Enthält das Framework mit grundlegenden Infrastrukturkomponenten:

- **Analytics**: System zur Erfassung und Analyse von Anwendungsdaten
- **Attributes**: Attribute/Annotations für Metadaten
- **Cache**: Caching-Mechanismen
- **CommandBus**: Command-Handling-Komponenten
- **Config**: Konfigurationsverwaltung
- **Console**: Konsolenanwendung und -befehle
- **Core**: Kernkomponenten und Events
- **DI**: Dependency-Injection-Container
- **ErrorHandling**: Fehlerbehandlungsmechanismen
- **EventBus**: Event-Handling-System
- **Exception**: Framework-Exceptions
- **Filesystem**: Dateisystemoperationen
- **Http**: HTTP-Request/Response-Handling
- **HttpClient**: HTTP-Client für externe API-Aufrufe
- **Logging**: Logging-Infrastruktur
- **Performance**: Performance-Monitoring
- **Queue**: Nachrichtenwarteschlangen
- **Redis**: Redis-Integration
- **Router**: URL-Routing
- **StaticSite**: Statische Site-Generation
- **Validation**: Datenvalidierung
- **View**: Template-Rendering

#### `/src/Application`

Anwendungsspezifische Komponenten, die das Framework nutzen.

#### `/src/Domain`

Domain-Modelle, Entities und Business-Logik.

#### `/src/Infrastructure`

Infrastrukturkomponenten, die externe Systeme integrieren.

#### `/src/Config`

Konfigurationsdateien für verschiedene Module.

## Framework-Architektur

### Dependency Injection

Das System nutzt einen leistungsfähigen DI-Container zur Verwaltung von Services:

```php
#[Initializer]
class ServiceInitializer
{
    public function __invoke(Container $container): Service
    {
        // Service erstellen und zurückgeben
    }
}
```

### Event-System

Ein Event-System ermöglicht lose Kopplung zwischen Komponenten:

```php
$eventDispatcher->addHandler(EventClass::class, function($event) {
    // Event verarbeiten
});
```

### HTTP-Pipeline

HTTP-Requests durchlaufen eine Middleware-Pipeline:

```php
class CustomMiddleware implements Middleware
{
    public function process(Request $request, callable $next): Response
    {
        // Request verarbeiten
        $response = $next($request);
        // Response verarbeiten
        return $response;
    }
}
```

## Module und ihre Interaktionen

### Analytics-Modul

Das Analytics-Modul erfasst und analysiert Anwendungsdaten:

- **Events tracken**: `$analytics->track('event_name', $properties)`
- **HTTP-Tracking**: Automatisch durch `AnalyticsMiddleware`
- **Error-Tracking**: Integration mit dem Error-Handling-System
- **Dashboard**: Admin-Interface zur Datenvisualisierung

### Konfigurationssystem

Konfigurationen werden zentral verwaltet und injiziert:

```php
class Service
{
    public function __construct(private Configuration $config)
    {
        $settings = $this->config->get('module_name', $defaults);
    }
}
```

## Erweiterbarkeit

### Neue Module hinzufügen

1. Erstellen Sie ein neues Verzeichnis unter `/src/Framework`
2. Implementieren Sie eine Initializer-Klasse mit dem `#[Initializer]`-Attribut
3. Erstellen Sie eine entsprechende Konfigurationsdatei unter `/src/Config`

### Middleware hinzufügen

```php
// In Ihrer Anwendungsklasse
public function bootstrap(): void
{
    $this->addMiddleware(YourMiddleware::class);
}
```

## Best Practices

- **Dependency Injection**: Verwenden Sie Constructor-Injection für Abhängigkeiten
- **Interfaces**: Definieren Sie Interfaces für alle Services
- **Events**: Nutzen Sie Events für lose Kopplung zwischen Modulen
- **Konfiguration**: Externalisieren Sie Konfigurationen in dedizierte Dateien
- **Typsicherheit**: Nutzen Sie strenge Typisierung und readonly-Properties