# Architektur & Technologie

Dieses Dokument beschreibt die technische Architektur des Jomblo Online Shops.

## Systemübersicht

```mermaid
graph TD
    User((User)) --> NextJS["Next.js 15 (Frontend/Backend)"]
    NextJS --> AuthJS["Auth.js v5 (Security)"]
    NextJS --> DB[(PostgreSQL)]
    NextJS --> Redis[(Redis Cache)]
    NextJS --> Stripe[Stripe API]
    AuthJS --> DB
    NextJS --> ServerActions[Server Actions]
```

## Kerntechnologien

### 1. Next.js 15 (App Router)
Das Projekt nutzt den neuesten Next.js App Router. 
- **Server Components**: Standard für Datenabfrage.
- **Server Actions**: Zentrale Mutationsebene (siehe `actions/`).

### 2. Authentifizierung (Auth.js v5)
Implementiert in `auth.ts`.
- **Strategy**: JWT.
- **Adapter**: `@auth/pg-adapter` mit individuellem Postgres-Pool.
- **Providers**: Credentials (E-Mail/Passwort) und Google OAuth.
- **Besonderheit**: Rollenbasierte Zugriffskontrolle (RBAC) über das JWT/Session-Objekt (`user.role`).

### 3. Datenbank & Validierung
- **PostgreSQL**: Direkter Zugriff über `pg` Pool (`lib/db.ts`).
- **Zod**: Umfassende Schemavalidierung in `schemas/`. Alle Datenbankmodelle sind als Zod-Schemas definiert (`schemas/db.ts`).

### 4. Caching & Realtime (Redis)
- **Client**: `lib/redis-client.ts` nutzt das `redis` Paket.
- **Einsatz**: Geplant für Performance-Optimierung und Echtzeit-Features (Chat).

### 5. Payment (Stripe)
- **Integration**: `lib/stripe.ts` initialisiert den Stripe-Client.
- **Webhooks**: `app/api/stripe/webhook/route.ts` verarbeitet Events wie `checkout.session.completed` via `fulfillCheckout` Action.

## Datenmodell-Auszug (Zod)
- `UserSchema`: ID, Name, E-Mail, Rolle, Customer ID.
- `OrderSchema`: ID, Kunde, Betrag, Status, Adressen (UUID-basiert).

## Technical Integrity Standardization Suite

Um Boilerplate zu reduzieren und Sicherheit zu garantieren, folgt das Projekt diesen Mustern:

### 1. Repository Pattern (`lib/db/repositories/`)
Direkte SQL-Abfragen werden in Repositories gekapselt, die von `BaseRepository` erben. Dies ermöglicht zentrale Protokollierung und bessere Testbarkeit.
- `query<T>(sql, params)`: Rückgabe aller Zeilen.
- `queryOne<T>(sql, params)`: Rückgabe der ersten Zeile oder null.

### 2. Server Action Wrapper (`createServerAction`)
Alle neuen Server Actions MÜSSEN über `createServerAction` erstellt werden. Dies erzwingt:
- **Zod Validierung**: Automatisches Parsing des Inputs.
- **Security**: Optionale Authentifizierung (`requireAuth`) und Admin-Check (`requireAdmin`).
- **Rate Limiting**: Throttling basierend auf User-ID oder IP.
- **Fehlerbehandlung**: Mapping von `AppError` Klassen auf standardisierte `ActionResponse`.

### 3. Frontend Integration (`useAction`)
Der `useAction` Hook verwaltet den Lebenszyklus einer Server Action im Frontend:
- Reactive State: `isLoading`, `data`, `error`, `validationErrors`.
- Automatisches Feedback: Integriert mit `Sonner` für Erfolgs- und Fehlermeldungen (außer bei Validierungsfehlern, die im Formular angezeigt werden).

### 4. Umgebungsvariablen (`lib/env.ts`)
Alle kritischen Umgebungsvariablen werden beim Anwendungsstart via Zod validiert. Ein Fehlen führt zum sofortigen Programmabbruch ("Fail-Fast").