breakpilot-pwa/klausur-service/docs/Worksheet-Editor-Architecture.md

Visual Worksheet Editor - Architecture Documentation

Version: 1.0 Datum: 2026-01-23 Status: Implementiert

1. Übersicht

Der Visual Worksheet Editor ist ein Canvas-basierter Editor für die Erstellung und Bearbeitung von Arbeitsblättern. Er ermöglicht Lehrern, eingescannte Arbeitsblätter originalgetreu zu rekonstruieren oder neue Arbeitsblätter visuell zu gestalten.

1.1 Hauptfunktionen

• Canvas-basiertes Editieren mit Fabric.js
• Freie Positionierung von Text, Bildern und Formen
• Typografie-Steuerung (Schriftarten, Größen, Stile)
• Bilder & Grafiken hochladen und einfügen
• KI-generierte Bilder via Ollama/Stable Diffusion
• PDF/Bild-Export für Druck und digitale Nutzung
• Mehrseitige Dokumente mit Seitennavigation

1.2 Technologie-Stack

Komponente	Technologie	Lizenz
Canvas-Bibliothek	Fabric.js 6.x	MIT
PDF-Export	pdf-lib 1.17.x	MIT
Frontend	Next.js / React	MIT
Backend API	FastAPI	MIT
KI-Bilder	Ollama + Stable Diffusion	Apache 2.0 / MIT

2. Architektur

┌──────────────────────────────────────────────────────────────────────┐
│                    Frontend (studio-v2 / Next.js)                     │
│  /studio-v2/app/worksheet-editor/page.tsx                            │
│                                                                        │
│  ┌─────────────┐  ┌────────────────────────────┐  ┌────────────────┐ │
│  │  Toolbar    │  │     Fabric.js Canvas       │  │  Properties    │ │
│  │  (Links)    │  │     (Mitte - 60%)          │  │  Panel         │ │
│  │             │  │                            │  │  (Rechts)      │ │
│  │ - Select    │  │  ┌──────────────────────┐  │  │                │ │
│  │ - Text      │  │  │                      │  │  │ - Schriftart   │ │
│  │ - Formen    │  │  │    A4 Arbeitsfläche  │  │  │ - Größe        │ │
│  │ - Bilder    │  │  │    mit Grid          │  │  │ - Farbe        │ │
│  │ - KI-Bild   │  │  │                      │  │  │ - Position     │ │
│  │ - Tabelle   │  │  └──────────────────────┘  │  │ - Ebene        │ │
│  └─────────────┘  └────────────────────────────┘  └────────────────┘ │
│                                                                        │
│  ┌────────────────────────────────────────────────────────────────┐   │
│  │  Seiten-Navigation | Zoom | Grid | Export PDF                   │   │
│  └────────────────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────────────┐
│                 klausur-service (FastAPI - Port 8086)                 │
│  POST /api/v1/worksheet/ai-image     → Bild via Ollama generieren    │
│  POST /api/v1/worksheet/save         → Worksheet speichern           │
│  GET  /api/v1/worksheet/{id}         → Worksheet laden               │
│  POST /api/v1/worksheet/export-pdf   → PDF generieren                │
└──────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────────────┐
│                    Ollama (Port 11434)                                │
│  Model: stable-diffusion oder kompatibles Text-to-Image Modell       │
│  Text-to-Image für KI-generierte Grafiken                            │
└──────────────────────────────────────────────────────────────────────┘

3. Dateistruktur

3.1 Frontend (studio-v2)

/studio-v2/
├── app/
│   └── worksheet-editor/
│       ├── page.tsx                    # Haupt-Editor-Seite
│       └── types.ts                    # TypeScript Interfaces
│
├── components/
│   └── worksheet-editor/
│       ├── index.ts                    # Exports
│       ├── FabricCanvas.tsx            # Fabric.js Canvas Wrapper
│       ├── EditorToolbar.tsx           # Werkzeugleiste (links)
│       ├── PropertiesPanel.tsx         # Eigenschaften-Panel (rechts)
│       ├── AIImageGenerator.tsx        # KI-Bild Generator Modal
│       ├── CanvasControls.tsx          # Zoom, Grid, Seiten
│       ├── ExportPanel.tsx             # PDF/Bild Export
│       └── PageNavigator.tsx           # Mehrseitige Dokumente
│
├── lib/
│   └── worksheet-editor/
│       ├── index.ts                    # Exports
│       └── WorksheetContext.tsx        # State Management

3.2 Backend (klausur-service)

/klausur-service/backend/
├── worksheet_editor_api.py             # API Endpoints
└── main.py                             # Router-Registrierung

4. API Endpoints

4.1 KI-Bild generieren

POST /api/v1/worksheet/ai-image
Content-Type: application/json

{
  "prompt": "Ein freundlicher Cartoon-Hund der ein Buch liest",
  "style": "cartoon",
  "width": 512,
  "height": 512
}

Response:

{
  "image_base64": "data:image/png;base64,...",
  "prompt_used": "...",
  "error": null
}

Styles:

• realistic - Fotorealistisch
• cartoon - Cartoon/Comic
• sketch - Handgezeichnete Skizze
• clipart - Einfache Clipart-Grafiken
• educational - Bildungs-Illustrationen

4.2 Worksheet speichern

POST /api/v1/worksheet/save
Content-Type: application/json

{
  "id": "optional-existing-id",
  "title": "Englisch Vokabeln Unit 3",
  "pages": [
    { "id": "page_1", "index": 0, "canvasJSON": "{...}" }
  ],
  "pageFormat": {
    "width": 210,
    "height": 297,
    "orientation": "portrait"
  }
}

4.3 Worksheet laden

GET /api/v1/worksheet/{id}

4.4 PDF exportieren

POST /api/v1/worksheet/{id}/export-pdf

Response: PDF-Datei als Download

4.5 Worksheets auflisten

GET /api/v1/worksheet/list/all

5. Komponenten

5.1 FabricCanvas

Die Kernkomponente für den Canvas-Bereich:

• A4-Format: 794 x 1123 Pixel (96 DPI)
• Grid-Overlay: Optionales Raster mit Snap-Funktion
• Zoom/Pan: Mausrad und Controls
• Selection: Einzel- und Mehrfachauswahl
• Keyboard Shortcuts: Del, Ctrl+C/V/Z/D

5.2 EditorToolbar

Werkzeuge für die Bearbeitung:

Icon	Tool	Beschreibung
🖱️	Select	Elemente auswählen/verschieben
T	Text	Text hinzufügen (IText)
▭	Rechteck	Rechteck zeichnen
○	Kreis	Kreis/Ellipse zeichnen
―	Linie	Linie zeichnen
→	Pfeil	Pfeil zeichnen
🖼️	Bild	Bild hochladen
✨	KI-Bild	Bild mit KI generieren
⊞	Tabelle	Tabelle einfügen

5.3 PropertiesPanel

Eigenschaften-Editor für ausgewählte Objekte:

Text-Eigenschaften:

• Schriftart (Arial, Times, Georgia, OpenDyslexic, Schulschrift)
• Schriftgröße (8-120pt)
• Schriftstil (Normal, Fett, Kursiv)
• Zeilenhöhe, Zeichenabstand
• Textausrichtung
• Textfarbe

Form-Eigenschaften:

• Füllfarbe
• Rahmenfarbe und -stärke
• Eckenradius

Allgemein:

• Deckkraft
• Löschen-Button

5.4 WorksheetContext

React Context für globalen State:

interface WorksheetContextType {
  canvas: Canvas | null
  document: WorksheetDocument | null
  activeTool: EditorTool
  selectedObjects: FabricObject[]
  zoom: number
  showGrid: boolean
  snapToGrid: boolean
  currentPageIndex: number
  canUndo: boolean
  canRedo: boolean
  isDirty: boolean
  // ... Methoden
}

6. Datenmodelle

6.1 WorksheetDocument

interface WorksheetDocument {
  id: string
  title: string
  description?: string
  pages: WorksheetPage[]
  pageFormat: PageFormat
  createdAt: string
  updatedAt: string
}

6.2 WorksheetPage

interface WorksheetPage {
  id: string
  index: number
  canvasJSON: string  // Serialisierter Fabric.js Canvas
  thumbnail?: string
}

6.3 PageFormat

interface PageFormat {
  width: number   // in mm (Standard: 210)
  height: number  // in mm (Standard: 297)
  orientation: 'portrait' | 'landscape'
  margins: { top, right, bottom, left: number }
}

7. Features

7.1 Undo/Redo

• History-Stack mit max. 50 Einträgen
• Automatische Speicherung bei jeder Änderung
• Keyboard: Ctrl+Z (Undo), Ctrl+Y (Redo)

7.2 Grid & Snap

• Konfigurierbares Raster (5mm, 10mm, 15mm, 20mm)
• Snap-to-Grid beim Verschieben
• Ein-/Ausblendbar

7.3 Export

• PDF: Mehrseitig, A4-Format
• PNG: Hochauflösend (2x Multiplier)
• JPG: Mit Qualitätseinstellung

7.4 Speicherung

• Backend: REST API mit JSON-Persistierung
• Fallback: localStorage bei Offline-Betrieb

8. KI-Bildgenerierung

8.1 Ollama Integration

Der Editor nutzt Ollama für die KI-Bildgenerierung:

OLLAMA_URL = "http://host.docker.internal:11434"

8.2 Placeholder-System

Falls Ollama nicht verfügbar ist, wird ein Placeholder-Bild generiert:

• Farbcodiert nach Stil
• Prompt-Text als Beschreibung
• "KI-Bild (Platzhalter)"-Badge

8.3 Stil-Prompts

Jeder Stil fügt automatisch Modifikatoren zum Prompt hinzu:

STYLE_PROMPTS = {
    "realistic": "photorealistic, high detail",
    "cartoon": "cartoon style, colorful, child-friendly",
    "sketch": "pencil sketch, hand-drawn",
    "clipart": "clipart style, flat design",
    "educational": "educational illustration, textbook style"
}

9. Glassmorphism Design

Der Editor folgt dem Glassmorphism-Design des Studio v2:

// Dark Theme
'backdrop-blur-xl bg-white/10 border border-white/20'

// Light Theme
'backdrop-blur-xl bg-white/70 border border-black/10 shadow-xl'

10. Internationalisierung

Unterstützte Sprachen:

• 🇩🇪 Deutsch
• 🇬🇧 English
• 🇹🇷 Türkçe
• 🇸🇦 العربية (RTL)
• 🇷🇺 Русский
• 🇺🇦 Українська
• 🇵🇱 Polski

Translation Key: nav_worksheet_editor

11. Sicherheit

11.1 Bild-Upload

• Nur Bildformate (image/*)
• Client-seitige Validierung
• Base64-Konvertierung

11.2 CORS

Aktiviert für lokale Entwicklung und Docker-Umgebung.

12. Deployment

12.1 Frontend

cd studio-v2
npm install
npm run dev  # Port 3001

12.2 Backend

Der klausur-service läuft auf Port 8086:

cd klausur-service/backend
python main.py

12.3 Docker

Der Service ist Teil des docker-compose.yml.

13. Zukünftige Erweiterungen

• Tabellen-Tool mit Zellbearbeitung
• Vorlagen-Bibliothek
• Kollaboratives Editieren
• Drag & Drop aus Dokumentenbibliothek
• Integration mit Vocab-Worksheet