Enhance README with detailed project structure, content system architecture, and recent improvements. Added sections for CMS and domain types, updated GraphQL queries, and clarified DataService and PageMapper functionalities. Included instructions for adding new content components and improved documentation links.

2025-12-13 23:36:53 +01:00
parent b1a556dc6d
commit 671a769e43
1 changed files with 115 additions and 16 deletions
--- a/README.md
+++ b/README.md
@@ -56,21 +56,45 @@ npm run dev          # Nur Astro Frontend (Port 4321)
 ```
 /
 ├── middlelayer/          # GraphQL Middlelayer
+│   ├── __cms/            # Legacy Contentful-Typen (nicht mehr verwendet)
 │   ├── adapters/         # Datenquellen-Adapter (Mock, CMS, etc.)
-│   ├── config/           # Konfiguration
+│   │   ├── Mock/         # Mock-Adapter mit Mock-Daten
+│   │   │   ├── _cms/     # CMS Mock-Daten
+│   │   │   └── _i18n/    # i18n Mock-Daten
+│   │   ├── config.ts     # Adapter-Konfiguration
+│   │   └── interface.ts  # DataAdapter Interface
+│   ├── auth/             # Authentication & Authorization
+│   ├── config/           # Konfiguration (Cache, etc.)
+│   ├── mappers/          # Data Mapper (CMS → Domain)
+│   │   └── pageMapper.ts # Page-Transformationen
 │   ├── monitoring/       # Logging, Metrics, Tracing
 │   ├── plugins/          # Apollo Server Plugins
 │   ├── types/            # TypeScript Typen
-│   ├── utils/            # Utilities (Cache, Dataloader, etc.)
+│   │   ├── cms/          # CMS-spezifische Typen (für Mapper)
+│   │   ├── c_*.ts        # Domain Content-Item-Typen
+│   │   └── *.ts          # Weitere Domain-Typen
+│   ├── utils/            # Utilities
+│   │   ├── cache.ts      # Cache-Implementierung
+│   │   ├── cacheKeys.ts  # Cache-Key-Builder
+│   │   ├── dataServiceHelpers.ts # Helper für DataService
+│   │   ├── dataloaders.ts # Dataloader + GraphQLContext
+│   │   └── errors.ts     # Error-Klassen
+│   ├── dataService.ts    # DataService (Singleton)
 │   ├── index.ts          # Server Entry Point
 │   ├── schema.ts         # GraphQL Schema
 │   └── resolvers.ts      # GraphQL Resolvers
 │
 ├── src/                  # Astro Frontend
 │   ├── components/       # Astro Komponenten
+│   │   ├── cms/          # CMS Content-Komponenten
+│   │   └── ...           # Weitere Komponenten
 │   ├── layouts/          # Layout Templates
 │   ├── lib/              # Utilities & GraphQL Client
+│   │   ├── graphql/      # GraphQL Client & Queries
+│   │   ├── i18n/         # i18n-System
+│   │   └── utils/        # Utilities (Layout, Markdown, etc.)
 │   ├── pages/            # Astro Pages
+│   │   └── [locale]/     # Locale-basierte Routen
 │   └── styles/           # Global Styles
 │
 └── docs/                 # Dokumentation
@@ -181,19 +205,41 @@ query {
    }
  }
 }
-  }
-  
-  page(slug: "/") {
+
+# Content-System (mit Content-Items)
+query {
+  page(slug: "/components", locale: "de") {
    slug
    name
    headline
-  }
-  
-  navigation {
-    name
-    links {
-      name
-      url
+    row1 {
+      justifyContent
+      alignItems
+      content {
+        ... on HTMLContent {
+          type
+          name
+          html
+        }
+        ... on MarkdownContent {
+          type
+          name
+          content
+          alignment
+        }
+        ... on HeadlineContent {
+          type
+          text
+          tag
+          align
+        }
+        ... on ImageContent {
+          type
+          name
+          imageUrl
+          caption
+        }
+      }
    }
  }
 }
@@ -210,7 +256,11 @@ Frontend (Astro)
    ↓
 GraphQL API (Apollo Server)
    ↓
-DataService (Singleton)
+Resolvers (mit Error Handling Wrapper)
+    ↓
+DataService (Singleton, mit Cache + Metrics)
+    ↓
+PageMapper (CMS → Domain Transformation)
    ↓
 DataAdapter (Interface)
    ↓
@@ -224,6 +274,31 @@ DataAdapter (Interface)
 - Testbarkeit durch Mock-Adapter
 - Zentrale Logik im DataService
 - Caching auf Service-Ebene
+- Type-safe Mapping von CMS zu Domain-Typen
+- Konsistentes Error Handling
+- Zentralisierte Cache-Keys
+- Strategy Pattern für wartbaren Code
+
+### Content-System
+
+Das System verwendet eine **Zwei-Schichten-Typ-Architektur**:
+
+1. **CMS-Typen** (`types/cms/`) - Wie Daten vom CMS kommen
+   - `*Skeleton` Wrapper mit `contentTypeId` und `fields`
+   - Verwendet `ComponentLayout` (Alias für `contentLayout`)
+   - Nur für Mapper und Mock-Daten
+
+2. **Domain-Typen** (`types/c_*.ts`) - Wie Daten in der App verwendet werden
+   - `c_*` Content-Item-Typen mit `type`-Feld
+   - Verwendet `contentLayout` direkt
+   - Für GraphQL Schema, Astro Components, etc.
+
+3. **PageMapper** - Konvertiert CMS-Typen zu Domain-Typen
+   - Strategy Pattern für wartbaren Code
+   - Automatische Transformation aller Content-Types
+
+**Content-Komponenten:**
+- HTML, Markdown, Iframe, ImageGallery, Image, Quote, YoutubeVideo, Headline

 ### Frontend

@@ -250,11 +325,16 @@ npm run preview        # Preview Production Build
 ```typescript
 // middlelayer/adapters/myAdapter.ts
 import type { DataAdapter } from './interface.js';
+import type { Page, Product, PageSeo, Navigation } from '../types/index.js';

 export class MyAdapter implements DataAdapter {
  async getProducts(limit?: number): Promise<Product[]> {
    // Implementierung
  }
+  async getPage(slug: string, locale?: string): Promise<Page | null> {
+    // Implementierung - muss CMS-Typen zurückgeben
+    // PageMapper konvertiert automatisch zu Domain-Typen
+  }
  // ... weitere Methoden
 }
 ```
@@ -271,6 +351,14 @@ export function createAdapter(): DataAdapter {
 }
 ```

+### Content-Komponenten hinzufügen
+
+1. CMS-Typ erstellen: `middlelayer/types/cms/MyComponent.ts`
+2. Domain-Typ erstellen: `middlelayer/types/c_myComponent.ts`
+3. Mapper erweitern: In `pageMapper.ts` Strategy Map erweitern
+4. GraphQL Schema erweitern: In `schema.ts` neuen Type hinzufügen
+5. Astro Component erstellen: `src/components/cms/C_myComponent.astro`
+
 ## 📈 Monitoring

 ### Prometheus Metrics
@@ -331,9 +419,11 @@ curl http://localhost:9090/metrics

 ## 📚 Weitere Dokumentation

- [Architektur & Skalierung](./docs/ARCHITECTURE_SCALING.md) - Detaillierte Architektur-Analyse
- [Redis Setup](./middlelayer/utils/REDIS_SETUP.md) - Redis Cache Konfiguration
+- [Type Structure](./middlelayer/types/README.md) - Detaillierte Typ-Struktur (CMS vs Domain)
+- [Authentication](./middlelayer/auth/README.md) - Authentication & Authorization
 - [Monitoring](./middlelayer/monitoring/README.md) - Monitoring & Observability
+- [Redis Setup](./middlelayer/utils/REDIS_SETUP.md) - Redis Cache Konfiguration
+- [Improvements](./middlelayer/IMPROVEMENTS.md) - Verbesserungsvorschläge & umgesetzte Änderungen

 ## 🐛 Bekannte Probleme

@@ -408,6 +498,15 @@ query {
 }
 ```

+## ✨ Kürzlich implementierte Verbesserungen
+
+- ✅ **Strategy Pattern** im PageMapper (statt 8 if-Statements)
+- ✅ **Code-Duplikation reduziert** in DataService (Helper-Klassen)
+- ✅ **Konsistentes Error Handling** (Wrapper-Funktion für alle Resolver)
+- ✅ **Zentralisierte Cache-Keys** (CacheKeyBuilder)
+- ✅ **Type Safety verbessert** (keine `any` Types mehr)
+- ✅ **User-Formatierung zentralisiert** (Helper-Funktion)
+
 ## 🔮 Roadmap

 - [ ] Query Complexity Schema-Realm-Problem dauerhaft lösen
@@ -416,7 +515,7 @@ query {
  - [ ] Locale-spezifische Inhalte implementieren
  - [ ] Fallback-Locales konfigurieren
 - [ ] Rate Limiting
- [ ] Authentication/Authorization ✅ (implementiert)
+- [x] Authentication/Authorization ✅ (implementiert)
 - [ ] GraphQL Subscriptions
 - [ ] i18n: Weitere Sprachen hinzufügen
 - [ ] i18n: Locale-spezifische Mock-Daten für CMS