managarten/games/worldream/docs/Refactoring-Analyse.md

Worldream - Refactoring Analyse & Empfehlungen

Executive Summary

Worldream ist eine gut strukturierte SvelteKit-Anwendung mit modernem Tech-Stack (Svelte 5, TypeScript, Tailwind CSS). Das Projekt zeigt solide Grundlagen, hat aber durch schnelle Entwicklung typische Problembereiche entwickelt, die durch strategisches Refactoring erheblich verbessert werden können.

🎯 Hauptproblembereiche

1. Code-Duplikation (🔴 HOCH)

Problem:

• Massive Duplikation zwischen world-context (/worlds/[world]/) und global context Seiten
• Identische Form-Handler und Validation-Logic über 40+ Dateien
• Wiederholte Fetch-Patterns und Error-Handling

Beispiel:

src/routes/characters/new/+page.svelte       (409 Zeilen)
src/routes/worlds/[world]/characters/new/+page.svelte (409 Zeilen)

Beide Dateien sind praktisch identisch bis auf URL-Pfade.

Auswirkung:

• 3x höhere Maintenance-Last
• Inkonsistente Features zwischen Kontexten
• Bug-Fixes müssen mehrfach angewendet werden

2. Fehlende Abstraktionen (🔴 HOCH)

Problem:

• Keine wiederverwendbare Form-Components
• API-Calls hart in Components kodiert
• Fehlende Data-Layer/Services

Beispiel:

// In 12+ Komponenten dupliziert:
const response = await fetch('/api/nodes', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({...})
})

3. Component-Architektur Probleme (🟡 MITTEL)

Problem:

• Sehr große, monolithische Components (400+ Zeilen)
• Mixed Concerns (UI + Business Logic + API calls)
• Schwer testbare Components

Beispiel:

• NodeEditForm.svelte: 375 Zeilen mit Form-Logic, Validation, API-Calls
• characters/new/+page.svelte: 409 Zeilen - sollte mehrere Components sein

4. Styling Inkonsistenzen (🟡 MITTEL)

Problem:

• CSS-Klassen über 12 Dateien dupliziert
• Keine Design System Component Library
• Hardcodierte Theme-Klassen statt CSS Custom Properties

Beispiel:

<!-- In 12+ Dateien identisch: -->
<form class="space-y-6 rounded-lg bg-theme-bg-surface p-6 shadow"></form>

5. Type Safety Lücken (🟡 MITTEL)

Problem:

• any Types in API responses (response?: any)
• Fehlende Input Validation Types
• Lose Type Definitions für Content Data

🚀 Refactoring-Roadmap

Phase 1: Immediate Wins (2-3 Tage)

1.1 Service Layer einführen

// src/lib/services/nodeService.ts
export class NodeService {
  static async create(node: CreateNodeRequest): Promise<ContentNode> {...}
  static async update(id: string, node: UpdateNodeRequest): Promise<ContentNode> {...}
  static async delete(id: string): Promise<void> {...}
  static async list(filters: NodeFilters): Promise<ContentNode[]> {...}
}

1.2 Shared Form Components

<!-- src/lib/components/forms/NodeForm.svelte -->
<script lang="ts">
	interface Props {
		mode: 'create' | 'edit';
		kind: NodeKind;
		initialData?: Partial<ContentNode>;
		worldSlug?: string;
		onSubmit: (data: NodeFormData) => Promise<void>;
		onCancel: () => void;
	}
</script>

1.3 Route Konsolidierung

Zentralisierte Route-Handler mit Context-Detection:

// Statt separate /characters/new und /worlds/[world]/characters/new
// Eine shared Component mit worldContext-Parameter

Phase 2: Architecture Improvements (1 Woche)

2.1 Component Aufspaltung

NodeEditForm.svelte (375 Zeilen) →
├── BasicInfoFields.svelte
├── ContentFields.svelte
├── OptionalFields.svelte
└── ActionButtons.svelte

2.2 Custom Stores für Business Logic

// src/lib/stores/nodeStore.ts
export const nodeStore = createNodeStore() {
  // CRUD Operations
  // Caching
  // Optimistic Updates
  // Error Handling
}

2.3 Design System

src/lib/ui/
├── Button.svelte
├── Input.svelte
├── Textarea.svelte
├── Form.svelte
├── Card.svelte
└── index.ts

Phase 3: Advanced Optimizations (1-2 Wochen)

3.1 Type System Verbesserung

// Strenge Input Validation
export const CreateNodeSchema = z.object({
	kind: z.enum(['world', 'character', 'object', 'place', 'story']),
	title: z.string().min(1).max(200),
	slug: z.string().regex(/^[a-z0-9-]+$/)
	// ...
});

3.2 Performance Optimizations

• Lazy Loading für große Forms
• Virtual Scrolling für Listen
• Image Optimization Pipeline
• Caching Strategy

3.3 Testing Infrastructure

// Testbare Components durch Dependency Injection
export default function NodeEditForm({
  nodeService = new NodeService(),
  router = new Router(),
  // ...
}) {

📊 Refactoring Metriken

Vor Refactoring

Komponenten mit >300 Zeilen:    12 Dateien
Duplizierte Code-Blöcke:        47 Instanzen
API-Call Duplikation:           23 Instanzen
CSS-Klassen Duplikation:        156 Instanzen
Type-Safety Score:              6/10

Nach Refactoring (Ziel)

Komponenten mit >300 Zeilen:    2-3 Dateien
Duplizierte Code-Blöcke:        <5 Instanzen
API-Call Duplikation:           0 Instanzen
CSS-Klassen Duplikation:        <10 Instanzen
Type-Safety Score:              9/10

🛠 Konkrete Refactoring Steps

Step 1: Service Layer (Tag 1)

1. Erstelle src/lib/services/nodeService.ts
2. Migriere API-Calls aus 5 wichtigsten Components
3. Update entsprechende Components

Step 2: Shared Components (Tag 2)

1. Erstelle NodeForm.svelte basierend auf NodeEditForm.svelte
2. Refactore characters/new/+page.svelte zur Nutzung von NodeForm
3. Update world-context Version

Step 3: Route Konsolidierung (Tag 3)

1. Erstelle shared NodeCreatePage.svelte
2. Update Router um Context-Detection
3. Entferne duplizierte Route-Dateien

Wöchentliche Ziele

• Woche 1: Service Layer + Basic Components
• Woche 2: Route Konsolidierung + Design System
• Woche 3: Advanced Features + Performance
• Woche 4: Testing + Documentation

🔧 Empfohlene Tools

Development

• Storybook: Component Library Development
• Vitest: Testing Framework
• TypeScript Strict Mode: Bessere Type Safety
• ESLint Custom Rules: Code Quality Durchsetzung

Monitoring

• Bundle Analyzer: Code Splitting Optimierung
• Lighthouse: Performance Tracking
• SvelteKit Analyzer: Bundle Size Monitoring

⚠️ Risiken & Mitigation

Risiken

1. Breaking Changes: Große Refactorings können Features brechen
2. Development Velocity: Kurzfristige Verlangsamung
3. Learning Curve: Neue Patterns für das Team

Mitigation Strategies

1. Feature Flags: Graduelle Rollouts
2. Comprehensive Testing: Vor und nach Refactoring
3. Documentation: Klare Migration Guides
4. Pair Programming: Wissenstransfer sicherstellen

📈 ROI Erwartung

Kurzfristig (1 Monat)

• 40% weniger Code-Duplikation
• 60% schnellere Feature-Entwicklung
• Weniger Bugs durch zentrale Validation

Mittelfristig (3 Monate)

• 70% weniger Maintenance-Aufwand
• Bessere Developer Experience
• Einfachere Onboarding neuer Entwickler

Langfristig (6+ Monate)

• Skalierbare Architektur für neue Features
• Höhere Code-Qualität und Testbarkeit
• Solide Basis für Performance-Optimierungen

🎯 Priorisierungs-Matrix

Task	Impact	Effort	Priority
Service Layer	Hoch	Niedrig	🔴 Sofort
Shared Forms	Hoch	Mittel	🔴 Sofort
Route Cleanup	Mittel	Niedrig	🟡 Diese Woche
Design System	Mittel	Hoch	🟡 Nächste Woche
Type Safety	Hoch	Hoch	🟢 Nächster Monat
Performance	Niedrig	Hoch	🟢 Later

💡 Langfristige Architektur-Vision

Worldream v2.0 Architecture:
├── UI Layer (Svelte Components)
│   ├── Pages (Route-specific logic)
│   ├── Components (Reusable UI)
│   └── Layout (App structure)
├── Business Logic Layer
│   ├── Stores (State management)
│   ├── Services (API abstraction)
│   └── Utils (Helper functions)
├── Data Layer
│   ├── API (Backend communication)
│   ├── Cache (Client-side caching)
│   └── Validation (Type safety)
└── Infrastructure
    ├── Config (Environment setup)
    ├── Auth (Authentication logic)
    └── Routing (Navigation handling)

---

Nächste Schritte: Beginnen Sie mit der Service Layer Implementierung und der Shared Form Component-Erstellung. Diese beiden Änderungen werden den größten sofortigen Impact haben und als Basis für weitere Refactorings dienen.