Visual Worksheet Editor - Architecture Documentation¶

Version: 1.0 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