lemonspace_app/.docs/LemonSpace_PRD.md

# 🍋 LemonSpace
## Product Requirements Document
*Self-Hosted, Source-Available Alternative to Freepik Spaces*

| Version | Status | Datum | Projekt |
|---------|--------|-------|---------|
| v2.1 | Draft | April 2026 | lemonspace.app |

---

## Changelog

| Version | Änderung |
|---------|----------|
| v0.2 | KI-Integrationsstrategie: OpenRouter als primäre AI-Layer, Freepik API auf Stock-Assets reduziert |
| v0.3 | Agent Layer eingeführt: Agent Nodes als Canvas-native Smart Batch Processor |
| v0.4 | Vollständige Node-Taxonomie: fünf Kategorien, Semantik je Node-Typ |
| v0.5 | Auth: Better Auth. Pricing: 4-Tier-Abo, Credit-System 30% Marge. Tailwind v4 bestätigt |
| v0.6 | Lizenz: BSL 1.1 mit 3-Jahres-Change-Date zu Apache 2.0 |
| v0.7 | Tech Stack: Redis, Zod, Unsend + Stalwart, Rybbit, Sentry, Cloudflare |
| v0.8 | Text-Overlay Node eingeführt (Kategorie 5: Canvas & Layout) |
| v0.9 | Zwei-Repo-Strategie (Web-App + Landing Page), Auth-Cookie-Sharing |
| v1.0 | Self-Hosting-Strategie, Credit Reservation+Commit, UX-Latenzen/Skeleton-Nodes, Convex Lock-in dokumentiert |
| v1.1 | Monorepo verworfen → Zwei unabhängige Repos (lemonspace-web + lemonspace-landing), Auth-Cookie-Sharing via .lemonspace.io |
| v1.2 | Pricing überarbeitet: Credit-Abstraktion (1 Cr = €0,01 intern), Tiers €8/€59/€119 (Business→Max), Top-Up-System (fix + Custom mit Bonus-Staffel), Marge nach LS-Gebühr + USt validiert |
| v1.3 | Payment: Lemon Squeezy → Polar.sh (niedrigere Gebühren, Better Auth Plugin, Open Source). Gebührenmodell angepasst: 4% + $0,40 + 1,5% intl. + 0,5% Subscription |
| v1.4 | Bildbearbeitung: Neue Kategorie 4 „Bildbearbeitung" mit non-destruktivem Adjustment-Stack (zwischen Transformation und Steuerung). 4 Adjustment-Nodes (Kurven, Farbe, Licht, Detail) + Render-Node. Alle Operationen credit-frei (client-seitig via Canvas API / WebGL). Steuerung → Kat. 5, Canvas & Layout → Kat. 6. Phase 2. |
| v1.5 | Stage 3 Offline Sync: Local-First Canvas mit IndexedDB Queue, Optimistic Updates, ID-Remapping. Magic Link Auth via Better Auth Plugin. react-resizable-panels für Sidebar Resizing. Canvas Modularisierung, Dashboard Dialoge, Auth Race-Härtung.|
| v2.0 | **Phase-1-Umfang erweitert:** Video- und Asset-Nodes vorgezogen (Phase 2→1). Bildbearbeitungs-Nodes (Kurven, Farbe, Licht, Detail, Render) vorgezogen (Phase 2→1). Vollständige WebGL-basierte Image-Pipeline implementiert (`lib/image-pipeline/`). Node-Taxonomie hat 6 Kategorien mit 27 Node-Typen. Phase-1-Status-Tabelle aktualisiert. |
| v2.1 | **Alle 9 Image-Modelle aktiviert (Phase 2→1):** Vollständige OpenRouter Image Gen Integration mit serverseitigem Tier-Enforcement und modellspezifischen Request-Modalities. Tier-aware Model Selector im Prompt-Node. AI-Modularisierung: `ai_errors.ts`, `ai_node_data.ts`, `ai_retry.ts` aus `ai.ts` extrahiert. Dashboard Snapshot Cache (`convex/dashboard.ts`): Gebündelte Query mit localStorage-Cache (`lib/dashboard-snapshot-cache.ts`). Credits Activity Analytics: `lib/credits-activity.ts` + `CreditsActivityChart` (Recharts). Canvas Graph Query Cache (`convex/canvasGraph.ts` + `canvas-graph-query-cache.ts`): Performance-Optimierung durch separaten Graph-Endpunkt mit Optimistic Store. Neuer Hook `use-dashboard-snapshot.ts`. ShadCN Chart-Komponente (`components/ui/chart.tsx`) + Recharts 3.8. |

---

## 1. Vision & Zielsetzung

LemonSpace ist eine self-hosted, source-available Alternative zu Freepik Spaces — ein kollaboratives, KI-gestütztes Creative-Workflow-Tool mit einer Infinite-Canvas-Oberfläche. Ziel ist ein freier und erweiterbarer Workspace für kreative Teams, der auf eigener Infrastruktur betrieben werden kann.

---

## 2. Problemstellung

Freepik Spaces ist ein leiststarkes Tool für KI-gestützte kreative Workflows, aber:

- Proprietäres SaaS-Produkt ohne Self-Hosting-Option
- Nutzer abhängig von Freepiks Pricing und Verfügbarkeit
- Keine Anpassbarkeit oder Erweiterbarkeit
- Datenschutzbedenken bei der Speicherung kreativer Assets auf externen Servern

---

## 3. Zielgruppe

| Segment | Primärer Zugang | Beschreibung |
|---------|-----------------|--------------|
| Designer & kreative Teams | Gehostete Version (lemonspace.app) | Datensouveränität ohne technischen Aufwand — zahlende Kernkunden |
| Entwickler & Tech-Teams | Self-Hosted | Anpassbare KI-Canvas-Plattform auf eigener Infra |
| Compliance-sensible Unternehmen | Self-Hosted | Regulatorische Anforderungen, die Cloud-SaaS einschränken |
| Open-Source-Community | Self-Hosted / Contributing | Creative-Tools-Ökosystem, BSL-Lizenz bis Change Date |

---

## 4. Core Features

### 4.1 Infinite Canvas

- Zoom, Pan und Navigation auf einem unbegrenzten Canvas
- Nodes als wiederverwendbare kreative Bausteine
- Drag & Drop von Assets, KI-Outputs und Mediendateien
- Gruppierung und Layering von Canvas-Elementen
- Resizable Sidebar mit Rail-Mode (collapsible)
- Offline-fähige Sync-Queue (IndexedDB + localStorage)
- Optimistic Updates mit ID-Remapping

### 4.2 Node-System

Das Canvas-System basiert auf einem erweiterbaren Node-Modell. Nodes sind typisierte Bausteine, die untereinander verbunden werden und Daten weitergeben. Es gibt **sechs Kategorien** mit insgesamt **27 Node-Typen**.

> **Single Source of Truth:** Die Node-Taxonomie wird zentral in `lib/canvas-node-types.ts` (Typen), `lib/canvas-node-catalog.ts` (Katalog) und `components/canvas/node-types.ts` (React-Flow-Registrierung) verwaltet. Der Katalog bestimmt automatisch den `implemented`-Status basierend auf vorhandenen React-Flow-Komponenten.

#### Kategorie 1: Quelle

Quelle-Nodes bringen Inhalte in den Canvas.

| Node | Beschreibung | Phase | Implementiert |
|------|--------------|-------|---------------|
| Bild | Upload eigener Bilder (PNG, JPG, WebP) oder Einbindung per URL. Basis-Asset für alle weiteren Operationen. | 1 | ✅ |
| Text | Freitextfeld mit Markdown-Support. Enthält Inhalte (Copy, Brief, Beschreibung) — semantisch verschieden vom Prompt-Node. | 1 | ✅ |
| Video | Upload von Videodateien oder Einbindung per Link. Darstellung als Thumbnail-Node, Playback im Panel. | 1 | ✅ |
| Asset | Stock-Assets (Fotos, Vektoren, Icons), direkt aus dem Asset Browser auf den Canvas gezogen. | 1 | ✅ |
| Farbe / Palette | Definiert Farben oder Farbpaletten als Style-Referenz. Kann an KI-Nodes oder Style-Transfer übergeben werden. | 2 | ☐ |
| Prompt | Dedizierter Node für Modellinstruktionen. Verbindet sich ausschließlich mit KI-Nodes. Kategorie: KI-Ausgabe. | 1 | ✅ |

#### Kategorie 2: KI-Ausgabe

KI-Ausgabe-Nodes sind das Ergebnis einer Modell-Operation. Sie werden vom System erzeugt, nicht vom Nutzer angelegt.

| Node | Beschreibung | Phase | Implementiert |
|------|--------------|-------|---------------|
| KI-Bild (`ai-image`) | Output eines Bildgenerierungs-Calls. Speichert Prompt, verwendetes Modell und Generierungsparameter. | 1 | ✅ |
| KI-Text | Output eines Text/Reasoning-Calls. Enthält generierten Copy, Captions, strukturierte Texte. | 2 | ☐ |
| KI-Video | Output eines Videogenerierungs-Calls. Keyframe-basierte Generierung aus Bild-Input möglich. | 2 | ☐ |
| Agent-Ausgabe | Bundle-Output eines Agent Nodes. Kann mehrere typisierte Sub-Outputs enthalten. | 3 | ☐ |

#### Kategorie 3: Transformation

| Node | Beschreibung | Phase | Implementiert |
|------|--------------|-------|---------------|
| Crop / Resize | Freie Bildausschnitt-Auswahl direkt auf dem Canvas, mit Aspect-Ratio-Lock. | 2 | ☐ |
| BG entfernen | Hintergrundentfernung via rembg. Output ist ein freigestelltes Bild. Batch-Modus möglich. | 2 | ☐ |
| Upscale | Hochskalierung via Real-ESRGAN. Unterstützt Faktoren 2×, 4×, 8×. | 2 | ☐ |
| Style Transfer | Überträgt visuellen Stil eines Referenzbildes auf einen anderen Input. | 3 | ☐ |
| Gesicht | Face Restoration via GFPGAN. Verbessert Gesichtsdetails in generierten oder degradierten Bildern. | 3 | ☐ |

#### Kategorie 4: Bildbearbeitung

Bildbearbeitungs-Nodes arbeiten **non-destruktiv**. Sie verändern das Originalbild nicht, sondern definieren Adjustments, die als Stack auf das Eingangsbild angewendet werden. Erst der Render-Node materialisiert das Ergebnis als neues Bild.

**Architektur: WebGL-basierte Image-Pipeline (`lib/image-pipeline/`)**

Die Bildbearbeitung nutzt eine vollständige WebGL-Pipeline für hardwarebeschleunigte Bildverarbeitung direkt im Browser:

```
lib/image-pipeline/
├── adjustment-types.ts    ← Typen und Default-Werte für alle Adjustments
├── contracts.ts           ← Pipeline-Schnittstellen
├── render-core.ts         ← Kern-Rendering-Logik
├── render-types.ts        ← Render-Typen
├── render-size.ts         ← Größenberechnung
├── source-loader.ts       ← Bildquellen-Lader
├── preview-renderer.ts    ← Echtzeit-Vorschau
├── histogram.ts           ← Histogram-Berechnung
├── histogram-plot.ts      ← Histogram-Visualisierung
├── presets.ts             ← Built-in und User-Presets
├── bridge.ts              ← Worker-Bridge
├── worker-client.ts       ← Web-Worker-Client
├── image-pipeline.worker.ts ← Web-Worker für Hintergrundverarbeitung
└── backend/
    ├── backend-router.ts  ← Backend-Auswahl (WebGL/WASM)
    ├── backend-types.ts   ← Backend-Typen
    ├── capabilities.ts    ← Feature-Erkennung
    ├── feature-flags.ts   ← Backend-Flags
    ├── webgl/
    │   ├── webgl-backend.ts  ← WebGL-Renderer
    │   └── shaders/          ← GLSL-Shader
    │       ├── curves.frag.glsl
    │       ├── color-adjust.frag.glsl
    │       ├── light-adjust.frag.glsl
    │       └── detail-adjust.frag.glsl
    └── wasm/
        ├── wasm-loader.ts    ← WASM-Loader (zukünftig)
        └── wasm-backend.ts   ← WASM-Backend (zukünftig)
```

**Adjustment-Stack:**

```
Bild-Node (Original)
  → Kurven-Node (Kontrast-S-Kurve)
    → Farbe-Node (Sättigung +20, Tint Warm)
      → Detail-Node (Sharpen 40%)
        → Render-Node → Neues Bild (materialisiert)
```

| Node | Beschreibung | Phase | Implementiert |
|------|--------------|-------|---------------|
| Kurven | Tonwert-Kurven (RGB + Einzelkanäle). Kontrollpunkte per Drag auf der Kurve. Presets: Kontrast, Aufhellen, Abdunkeln, Film-Look, Cross-Process. | 1 | ✅ |
| Farbe | HSL-Regler (Hue, Saturation, Luminance — global + pro Farbbereich). Color Balance. Temperature/Tint. Presets. | 1 | ✅ |
| Licht | Brightness, Contrast, Exposure, Highlights, Shadows, Whites, Blacks. HDR-Tone-Mapping. Vignette. Presets. | 1 | ✅ |
| Detail | Unscharf maskieren (Amount, Radius, Threshold). Clarity / Structure. Denoise. Grain. Presets. | 1 | ✅ |
| Render | Materialisierer: Wendet den gesamten Adjustment-Stack an und erzeugt ein neues Bild (in Convex Storage). Unterstützt Ausgabe-Auflösung und Format. | 1 | ✅ |

> **Credits:** Alle Adjustment-Nodes sind **credit-frei** — die Verarbeitung läuft vollständig im Browser (WebGL). Nur der Render-Node erzeugt serverseitig ein finales Bild (ebenfalls credit-frei).

> **Technische Umsetzung:** Die Entscheidung für WebGL als primäre Rendering-Engine ist getroffen. GLSL-Shader für alle vier Adjustment-Typen sind implementiert. Ein WASM-Backend ist als Alternative vorbereitet (`wasm-backend.ts`), aber noch nicht aktiv.

#### Kategorie 5: Steuerung & Flow

| Node | Semantik | Beschreibung | Phase | Implementiert |
|------|----------|--------------|-------|---------------|
| Splitter | 1 → N | Verteilt 1 Input auf N identische oder abgeleitete Outputs. | 2 | ☐ |
| Loop | Liste → N | Iteriert über eine Liste von Inputs und führt dieselbe verknüpfte Operation für jeden Eintrag aus. | 2 | ☐ |
| Agent | N → Plan → N | LLM-Orchestrator. Analysiert Inputs, plant strukturierten Ausführungsplan, delegiert Operationen. | 2 | ☐ |
| Mixer / Merge | N → 1 | Kombiniert N Inputs zu 1 Output durch Überblendung, Komposition oder Selektion. | 3 | ☐ |
| Weiche | 1 → Pfad A/B/... | Bedingter Router. Leitet den Input anhand einer definierbaren Bedingung auf einen von mehreren Ausgangspfaden. | 3 | ☐ |

#### Kategorie 6: Canvas & Layout

| Node | Beschreibung | Phase | Implementiert |
|------|--------------|-------|---------------|
| Gruppe | Container für andere Nodes. Unterstützt Collapse/Expand und benannte Scopes. | 1 | ✅ |
| Frame | Artboard mit definierter Auflösung. Dient als Export-Boundary. | 1 | ✅ |
| Notiz | Annotation auf dem Canvas. Markdown-Support, kein Datenanschluss. | 1 | ✅ |
| Compare | Stellt zwei Bilder nebeneinander mit interaktivem Slider dar. | 1 | ✅ |
| Text-Overlay | Editierbarer Text-Layer über Bild- oder Video-Nodes innerhalb eines Frames. | 2 | ☐ |
| Kommentar | Kollaborations-Node für Reviews. Unterstützt Threads, @mentions und Resolve-Status. | 3 | ☐ |
| Präsentation | Definiert Canvas-Bereiche als geordnete Slideshow. Export als PDF möglich. | 3 | ☐ |

### 4.3 Agent Nodes

Agent Nodes sind ein spezieller Node-Typ auf dem Canvas. Sie fungieren als Smart Batch Processor: Sie nehmen mehrere Input-Nodes entgegen, orchestrieren komplexe Multi-Step-Workflows über ein Text/Reasoning LLM und produzieren mehrere Output-Nodes direkt auf dem Canvas.

**Ausführungsphasen:**

1. **Analyse:** Agent erhält alle verbundenen Inputs, LLM prüft ob alle nötigen Informationen vorhanden sind
2. **Clarification (optional):** Fehlen Angaben, stellt der Agent gezielt Rückfragen direkt am Node
3. **Execution:** LLM plant einen strukturierten Output-Plan (JSON), der dann als Batch abgearbeitet wird
4. **Output:** Ergebnisse landen als neue Nodes auf dem Canvas, verbunden mit dem Agent Node

**Vordefinierte Agent Templates:**

| Template | Typische Inputs | Typische Outputs |
|----------|-----------------|------------------|
| Instagram Curator | Produktfotos, Brand Brief, Zielgruppe | Feed Posts, Text-Overlays, Captions, Hashtag-Sets |
| (weitere folgen) | — | — |

---

## 5. Tech Stack

| Bereich | Technologie | Version / Hinweis |
|---------|-------------|-------------------|
| Frontend Framework | Next.js | 16.1.1 — App Router, Server Components |
| Styling | Tailwind CSS | v4 |
| UI Komponenten | ShadCN/UI | Aktuelle stabile Version |
| Backend / Realtime | Convex | Self-hosted via convex-backend |
| Authentifizierung | Better Auth + Magic Link | Self-hosted, open-source, Magic Link via -sh/better-auth plugin |
| Canvas / Flow | @xyflow/react | ehem. react-flow-renderer |
| Drag & Drop | dnd-kit | Empfohlen über react-dnd (bessere Performance) |
| Deployment | Coolify | VPS-Deployment für alle Self-hosted Services |
| Payment | Polar.sh | MoR, VAT-Handling, Better Auth Plugin (@polar-sh/better-auth) |
| Input Validation | Zod | Frontend + Backend, Convex Mutations |
| In-Memory Store | Redis | Self-hosted via Coolify |
| Rate Limiting | Redis-backed | Next.js Middleware / Route Handler |
| E-Mail | Unsend + Stalwart | Self-hosted via Coolify |
| Analytics | Rybbit | Self-hosted via Coolify |
| Error Tracking | Sentry Cloud | Free Tier (5.000 Errors/Monat) |
| DNS / DDoS / CDN | Cloudflare | Domain-Routing, DDoS-Schutz, Asset-Caching |
| Panel Resizing | react-resizable-panels | ShadCN UI Komponente für Resizable Layouts |
| Image Pipeline | WebGL + GLSL Shaders | Hardware-beschleunigte Bildverarbeitung im Browser |
| Offline Sync | IndexedDB + localStorage | Canvas-Sync-Queue, Snapshot-Persistenz, Optimistic Updates |
| Package Manager | pnpm | Je Repo |
| Charts / Visualization | Recharts + ShadCN Chart | v3.8.0 — Dashboard Credits Activity Chart |

### Zwei-Repo-Strategie

Statt eines Monorepos werden zwei unabhängige Repositories gepflegt. Zwischen den Repos gibt es keinen geteilten Code — die Landing Page hat keine Abhängigkeit auf Convex-Schemas, Node-Types oder andere App-Logik.

| Repo | Domain | Inhalt |
|------|--------|--------|
| `lemonspace-web` | app.lemonspace.io | Next.js App (Canvas, Dashboard, Auth, AI, Convex) |
| `lemonspace-landing` | lemonspace.io | Next.js Marketing Site |

**Auth-Cookie-Sharing:** BetterAuth setzt einen Session-Cookie auf `.lemonspace.io` (Dot-Prefix = gilt für alle Subdomains). Die Landing Page liest diesen Cookie, um den Login-State zu erkennen und zwischen "Get Started" und "Dashboard" Button zu wechseln. Die Landing Page führt keine Auth-Operationen durch — sie liest nur den Cookie.

### Self-Hosting-Strategie

Self-Hosting richtet sich primär an technisch versierte Nutzer und Entwickler. Die gehostete Version (lemonspace.app) ist der empfohlene Weg für alle anderen — insbesondere für Designer und kreative Teams ohne DevOps-Erfahrung.

Das Self-Hosting-Paket umfasst:

- **`docker-compose.yml`** — fasst alle Services zusammen: Next.js, Convex, Redis, Stalwart, Rybbit, rembg, Real-ESRGAN, GFPGAN
- **`.env.example`** — alle Umgebungsvariablen mit Kommentaren und Standardwerten
- **Setup-README** — Schritt-für-Schritt-Anleitung (Voraussetzungen: Docker + Coolify oder plain Docker)

> **Hinweis:** Self-hosted KI-Services (rembg, Real-ESRGAN, GFPGAN) bleiben in separaten Repositories mit eigenem Docker/Infra-Lifecycle und werden über Coolify unabhängig deployt.

### Convex: Architektonische Entscheidung & Lock-in

Convex liefert Realtime-Sync, File Storage und Background Jobs out-of-the-box, ohne dass eine eigene WebSocket-Infrastruktur, S3-Integration und Queue-Lösung zusammengestückelt werden muss. Dieser Geschwindigkeitsvorteil rechtfertigt den bewussten Vendor Lock-in.

> **Risiko (bewusst akzeptiert):** Der gesamte Realtime-, Storage- und Job-Stack ist an Convex gebunden. Eine spätere Migration ist aufwändig. Es wird keine künstliche Abstraktionsschicht eingebaut, da sie den Kernvorteil von Convex aufheben würde.

Dokumentierter Migrationspfad bei Skalierung: Convex Cloud mit EU-Standort. Convex bietet das eigene Migrations-Tooling und kennt das Ökosystem. Self-hosted Convex bleibt die Default-Strategie für Phase 1.

---

## 6. KI-Integrationsstrategie

### Zwei LLM-Rollen im System

| Rolle | Zweck | Beispielmodelle | Aufgerufen von |
|-------|-------|-----------------|----------------|
| Text / Reasoning | Agent-Logik, Planung, Clarification, Copywriting | Claude 3.5 Sonnet, GPT-4o | Agent Node |
| Image Generation | Bildgenerierung auf dem Canvas | Gemini 2.5 Flash Image, Flux.1 Pro, GPT-5 Image | Canvas-Aktionen + Agent Node |

### OpenRouter — Image Generation

| Modell | OpenRouter ID | Stärke | ~Kosten/Bild |
|--------|---------------|--------|--------------|
| Gemini 2.5 Flash Image | google/gemini-2.5-flash-image | Multi-Turn Editing, günstig | ~€0,02–0,04 |
| FLUX.2 Klein 4B | black-forest-labs/flux.2-klein-4b | Photorealismus, schnellstes Flux | ~€0,01–0,03 |
| Seedream 4.5 | bytedance-seed/seedream-4.5 | Editing-Konsistenz, Portraits | ~€0,04 |
| Gemini 3.1 Flash Image | google/gemini-3.1-flash-image-preview | Pro-Qualität bei Flash-Speed | ~€0,04–0,08 |
| GPT-5 Image Mini | openai/gpt-5-image-mini | Gutes Preis-Leistungs-Verhältnis | ~€0,04–0,08 |
| Riverflow V2 Fast | sourceful/riverflow-v2-fast | Custom Font Rendering, schnell | ~€0,02 |
| Riverflow V2 Pro | sourceful/riverflow-v2-pro | Text-Rendering, 4K Output | ~€0,15–0,33 |
| Gemini 3 Pro Image | google/gemini-3-pro-image-preview | Multi-Image, 4K, bestes Text-Rendering | ~€0,08–0,15 |
| GPT-5 Image | openai/gpt-5-image | Instruction Following, Text in Bild | ~€0,10–0,20 |

### Aktuell aktivierte Modelle (Phase 1)

Alle 9 Image-Modelle sind aktiviert. Server-seitiges Tier-Enforcement prüft `minTier` pro Modell. Der Prompt-Node bietet einen tier-aware Model Selector.

| Modell | ID | Credits | Tier-Zugang | Modalities |
|--------|-----|---------|-------------|------------|
| Gemini 2.5 Flash | google/gemini-2.5-flash-image | 4 Cr | Alle Tiers | image + text |
| FLUX.2 Klein 4B | black-forest-labs/flux.2-klein-4b | 2 Cr | Alle Tiers | image only |
| Seedream 4.5 | bytedance-seed/seedream-4.5 | 5 Cr | Alle Tiers | image only |
| Gemini 3.1 Flash Image | google/gemini-3.1-flash-image-preview | 6 Cr | Alle Tiers | image + text |
| GPT-5 Image Mini | openai/gpt-5-image-mini | 8 Cr | Ab Starter | image + text |
| Riverflow V2 Fast | sourceful/riverflow-v2-fast | 9 Cr | Ab Starter | image only |
| Riverflow V2 Pro | sourceful/riverflow-v2-pro | 12 Cr | Ab Starter | image only |
| Gemini 3 Pro Image | google/gemini-3-pro-image-preview | 13 Cr | Ab Starter | image + text |
| GPT-5 Image | openai/gpt-5-image | 15 Cr | Ab Starter | image + text |

> **Request Modalities:** Modelle mit `image only` senden `modalities: ["image"]`, alle anderen `modalities: ["image", "text"]`. Dies wird in `convex/openrouter.ts` über das `requestModalities`-Feld gesteuert.

### Self-hosted Services

| Service | Funktion | Credits |
|---------|----------|---------|
| rembg | Hintergrundentfernung | Kostenlos |
| Real-ESRGAN | Upscaling (2×, 4×, 8×) | Kostenlos |
| GFPGAN | Face Restoration | Kostenlos |

---

## 7. High-Level Architektur

```
┌──────────────────────────────────────────────────────────┐
│ Next.js Frontend                                         │
│ Infinite Canvas (@xyflow/react + dnd-kit)                │
│                                                          │
│ Node-Kategorien:                                         │
│ [Quelle] [KI-Ausgabe] [Transformation]                   │
│ [Bildbearbeitung] [Steuerung] [Canvas & Layout]          │
│                                                          │
│ Image Pipeline:                                          │
│ WebGL + GLSL Shaders (client-seitig, credit-frei)        │
│ IndexedDB Sync Queue (offline-fähig)                     │
└───────────────────────┬──────────────────────────────────┘
                        │
              ┌─────────▼─────────┐
               │  Convex Backend   │
               │  (Self-hosted)    │
               │  - Realtime Sync  │
               │  - File Storage   │
               │  - Auth           │
               │  - Modell-Router  │
               │  - Agent Executor │
               └──┬────────┬───┬───┘
                  │        │   │
     ┌────────────▼──┐ ┌───▼──────────────┐ ┌──▼──────────┐
     │  OpenRouter   │ │ Self-hosted KI   │ │ Freepik API │
     │ Image Gen +   │ │ rembg / ESRGAN   │ │  (Assets)   │
     │ Text/Reason   │ │ GFPGAN           │ └─────────────┘
     └───────────────┘ └──────────────────┘
```

---

## 8. Datenmodell (High-Level)

### Canvas & Node

```
Canvas
├── id, name, ownerId, createdAt / updatedAt
└── nodes[]

Node (Basis)
├── id, canvasId
├── type (image | text | prompt | color | video | asset |
│        ai-image | ai-text | ai-video | agent-output |
│        crop | bg-remove | upscale | style-transfer | face-restore |
│        curves | color-adjust | light-adjust | detail-adjust | render |
│        splitter | loop | agent | mixer | switch |
│        group | frame | note | compare | text-overlay | comment | presentation)
├── position { x, y }
├── size { width, height }
├── data (je nach Typ)
├── status (idle | analyzing | clarifying | executing | done | error)
├── statusMessage?
├── retryCount?
├── parentId?
├── zIndex?
└── createdAt
```

### Credit-System

```
CreditBalance
├── id, userId
├── balance          // verfügbare Credits
├── reserved         // aktuell gesperrte Credits (laufende Jobs)
├── available        // computed: balance - reserved
├── monthlyAllocation // Credits aus dem Abo (50/400/3300/6700)
└── updatedAt

CreditTransaction
├── id, userId
├── amount           // positiv = Gutschrift, negativ = Verbrauch (in Credits)
├── type             // subscription | topup | usage | reservation | refund
├── status           // committed | reserved | released | failed
├── description      // z.B. "Bildgenerierung – Gemini 2.5 Flash Image (4 Cr)"
├── nodeId?          // Referenz auf den auslösenden Node
├── canvasId?        // Zugehöriger Canvas
├── openRouterCost?  // tatsächliche OpenRouter-Kosten in €
├── model?           // OpenRouter Model ID
└── createdAt

Subscription
├── id, userId
├── tier             // free | starter | pro | max | business
├── status           // active | cancelled | past_due | trialing
├── currentPeriodStart / currentPeriodEnd
└── polarSubscriptionId?
```

### Adjustment Presets

```
AdjustmentPreset
├── id, userId
├── name             // Benutzerdefinierter Name
├── nodeType         // curves | color-adjust | light-adjust | detail-adjust
├── params           // Typ-spezifische Parameter (v.any())
└── createdAt
```

---

## 9. Pricing & Credit-System

### Credit-Abstraktion

Nutzer arbeiten mit **Credits** statt mit Euro-Beträgen. Ein Credit entspricht intern €0,01 OpenRouter-Kosten (interner Wechselkurs, wird dem Nutzer nicht kommuniziert). Die Abstraktion entkoppelt das Pricing von API-Preisschwankungen und ermöglicht flexible Anpassungen.

### Abo-Stufen

Preise kalkuliert mit ≥28% Netto-Marge nach Polar Gebühr (4% + $0,40 + 1,5% intl. + 0,5% Subscription) und 19% USt.

| Tier | Preis/Monat | Credits/Monat | Echte Marge | €/Credit | Zielgruppe |
|------|-------------|---------------|-------------|----------|------------|
| Free | €0 | 50 | −€0,50 (Akquise) | gratis | Testen & Evaluieren |
| Starter | €8 | 400 | ~€2,00 (33%) | €0,0200 | Einzelnutzer, Einstieg |
| Pro | €59 | 3.300 | ~€13,71 (29%) | €0,0179 | Aktive Creator |
| Max | €119 | 6.700 | ~€27,61 (29%) | Teams, hoher Durchsatz |

### Credit-Nachkauf (Top-Up)

Fixe Top-Up-Pakete + frei wählbarer Custom-Betrag (€5–200). Top-Ups sind pro Credit immer teurer als das entsprechende Abo — regelmäßige Nachkäufer werden zum Upgrade animiert.

**Fixe Pakete:**

| Paket | Preis | Credits | Marge | €/Credit |
|-------|-------|---------|-------|----------|
| Klein | €5 | 250 | ~31% | €0,0200 |
| Mittel | €10 | 500 | ~34% | €0,0200 |
| Groß | €20 | 1.000 | ~36% | €0,0200 |
| XL | €50 | 3.000 | ~24% | €0,0167 |

**Custom Top-Up (€5–200):** Bonus steigt stufenweise mit dem Betrag. Formel: `Credits = FLOOR(Netto × 0,70 × (1 + Bonus) ÷ Kurs)`. UI zeigt live: "€X → Y Credits".

| Bereich | Bonus | Min. Marge |
|---------|-------|------------|
| €5–9,99 | 0% | ~30% |
| €10–19,99 | 3% | ~28% |
| €20–49,99 | 6% | ~26% |
| €50–99,99 | 10% | ~23% |
| €100–200 | 13% | ~21% |

### Credit-Preise pro Operation

Credits = ROUND(API-Kosten × Markup ÷ Kurs). Agent-Calls haben höheren Markup (Wertschöpfung durch Orchestrierung).

| Operation | Modell | API-Kosten | Markup | Credits | Tier-Zugang |
|-----------|--------|------------|--------|---------|-------------|
| Bildgenerierung (Standard) | Gemini 2.5 Flash | ~€0,04 | 1× | 4 Cr | Alle Tiers |
| Bildgenerierung (Budget) | FLUX.2 Klein 4B | ~€0,02 | 1× | 2 Cr | Alle Tiers |
| Bildgenerierung (Standard) | Seedream 4.5 | ~€0,05 | 1× | 5 Cr | Alle Tiers |
| Bildgenerierung (Standard+) | Gemini 3.1 Flash Image | ~€0,06 | 1× | 6 Cr | Alle Tiers |
| Bildgenerierung (Premium) | GPT-5 Image Mini | ~€0,08 | 1× | 8 Cr | Ab Starter |
| Bildgenerierung (Premium) | Riverflow V2 Fast | ~€0,09 | 1× | 9 Cr | Ab Starter |
| Bildgenerierung (Premium) | Riverflow V2 Pro | ~€0,12 | 1× | 12 Cr | Ab Starter |
| Bildgenerierung (Premium) | Gemini 3 Pro Image | ~€0,13 | 1× | 13 Cr | Ab Starter |
| Bildgenerierung (Ultra) | GPT-5 Image | ~€0,15 | 1× | 15 Cr | Ab Starter |
| Agent Reasoning (leicht) | Claude Sonnet | ~€0,03 | 3× | 9 Cr | Ab Starter |
| Agent Reasoning (mittel) | Claude Sonnet | ~€0,06 | 2,5× | 15 Cr | Ab Starter |
| Agent-Run (komplex) | Multi-Step Workflow | ~€0,15 | 2,5× | 38 Cr | Ab Starter |
| BG-Entfernung | rembg (self-hosted) | €0 | — | 0 Cr | Alle Tiers |
| Upscaling | Real-ESRGAN (self-hosted) | €0 | — | 0 Cr | Alle Tiers |
| Face Restoration | GFPGAN (self-hosted) | €0 | — | 0 Cr | Alle Tiers |
| Canvas-Operationen | — | €0 | — | 0 Cr | Alle Tiers |
| Bildbearbeitung (Kurven, Farbe, Licht, Detail) | WebGL (client-seitig) | €0 | — | 0 Cr | Alle Tiers |
| Render (Adjustment-Stack materialisieren) | Server-seitig (Canvas API) | €0 | — | 0 Cr | Alle Tiers |
| Export (PNG/ZIP) | — | €0 | — | 0 Cr | Alle Tiers |

### Credit Reservation + Commit

Credits werden vor jedem KI-Call reserviert und erst nach erfolgreichem Abschluss committed. Bei Fehler werden reservierte Credits automatisch freigegeben — kein manueller Refund-Prozess nötig.

**Flow:**

```
1. RESERVE → CreditTransaction (type: reservation, status: reserved)
   CreditBalance.reserved += estimated_credits
   CreditBalance.available = balance - reserved

2a. SUCCESS → Transaction status: committed
    CreditBalance.balance -= actual_credits
    CreditBalance.reserved -= estimated_credits

2b. FAILURE → Transaction status: released
    CreditBalance.reserved -= estimated_credits
    (balance bleibt unverändert — voller Refund)
```

> **Preisbasis:** Credit-Preise pro Operation sind fix definiert (siehe Tabelle). Der interne Wechselkurs (1 Credit = €0,01 OR-Kosten) ist ein internes Kalkulationsinstrument. Bei API-Preisänderungen werden die Credit-Preise pro Operation angepasst — nicht der Wechselkurs.

### Agent Partial Failure

Bei Agent-Workflows läuft Reservation + Commit pro Suboperation. Schlägt Step 3 von 5 fehl: Steps 1+2 sind committed, Step 3 wird released, Steps 4+5 werden nicht mehr reserviert. Nur tatsächlich verbrauchte Credits werden berechnet.

---

## 10. UX-Strategie für Latenzen

KI-Operationen haben inhärente Wartezeiten. Einzelne Bildgenerierungen dauern 3–15 Sekunden, Agent-Workflows 20–60+ Sekunden. Die UI überbrückt diese Wartezeiten durch optimistische Darstellung direkt am Node — kein globales Loading-Banner, kein blockierendes Modal.

### Node-Status-Modell

Jeder ausführende Node zeigt seinen Zustand visuell direkt auf dem Canvas:

```
idle → analyzing → clarifying → executing (Step X/N) → done | error
```

Agent Nodes zeigen zusätzlich den Step-Progress während der Execution ("Generating Feed Post 2/3"). Bei Fehler wechselt der Node in einen Error-State mit kurzem Hinweis direkt am Node ("Timeout — Credits wurden nicht abgebucht").

### Skeleton Nodes

Sobald der Agent seinen Execution-Plan (JSON) erstellt hat, kennt das System Anzahl und Typ aller Output-Nodes. Ab diesem Moment werden Skeleton-Nodes auf dem Canvas platziert — noch bevor ein einziger API-Call für die Generierung läuft.

```
Agent Status: analyzing
→ Plan fertig: 3x KI-Bild, 2x KI-Text, 1x Text-Overlay
→ 6 Skeleton-Nodes erscheinen auf dem Canvas, korrekt positioniert
→ Agent Status: executing (1/6)
→ Skeletons füllen sich der Reihe nach mit echten Outputs
```

- Skeleton-Nodes sind bereits verschiebbar und arrangierbar bevor der Output fertig ist
- Sobald der Output fertig ist, ersetzt er den Skeleton in-place — Position bleibt erhalten
- Visuell: gedimmter Node-Rahmen mit Shimmer-Effekt, Node-Typ-Icon sichtbar (Bild vs. Text)

### Browser Notifications (Tab-Wechsel)

- Opt-in Browser Notifications API: wenn der Nutzer den Tab verlässt und der Job fertig wird, native Browser-Benachrichtigung
- Nicht erzwungen — Nutzer die im Tab bleiben sehen den Node-Status direkt

### Offline-Sync & Optimistic Updates

- **IndexedDB-Sync-Queue** (`lib/canvas-op-queue.ts`): Persistente Queue für Canvas-Mutations mit Retry-Backoff und 24h-TTL
- **localStorage-Cache** (`lib/canvas-local-persistence.ts`): Snapshot + leichtgewichtiger Op-Mirror für sofortige UI-Pins/Recovery
- **Optimistic IDs:** Temporäre Nodes/Edges erhalten `optimistic_`-Prefix, werden durch echte Convex-IDs ersetzt
- **ID-Remapping:** Folge-Operationen werden automatisch auf neue IDs remappt

---

## 11. Entwicklungsphasen

### Phase 1 — Foundation (MVP)

**Nodes (15 implementiert):**
- Quelle: Bild ✅, Text ✅, Video ✅, Asset ✅
- KI-Ausgabe: Prompt ✅, KI-Bild (`ai-image`) ✅
- Bildbearbeitung: Kurven ✅, Farbe ✅, Licht ✅, Detail ✅, Render ✅
- Canvas & Layout: Gruppe ✅, Frame ✅, Notiz ✅, Compare ✅

**Infrastruktur & Features:**

| Task | Status |
|------|--------|
| Projektsetup: Next.js 16 + Tailwind v4 + ShadCN | ✅ Erledigt |
| Convex Self-hosted Backend | ✅ Erledigt |
| Basis-Canvas mit @xyflow/react | ✅ Erledigt |
| Drag & Drop von Bildern | ✅ Erledigt |
| Authentifizierung via Better Auth + Magic Link | ✅ Erledigt |
| OpenRouter Integration (Gemini 2.5 Flash Image) | ✅ Erledigt |
| Credit-System: Balance, Reservation+Commit | ✅ Erledigt |
| Abo-Verwaltung: Free/Starter/Pro/Max Tiers | ✅ Erledigt |
| Polar Integration: Checkout, Webhooks | ✅ Erledigt |
| Credit-Nachkauf: Fixe Top-Ups + Custom | ✅ Erledigt |
| Node-Status-Modell (idle/executing/done/error) | ✅ Erledigt |
| WebGL Image Pipeline (Adjustments) | ✅ Erledigt |
| Resizable Sidebar mit Rail-Mode | ✅ Erledigt |
| Offline Sync (IndexedDB Queue) | ✅ Erledigt |
| Optimistic Updates + ID-Remapping | ✅ Erledigt |
| Auth Race-Härtung | ✅ Erledigt |
| Canvas Modularisierung | ✅ Erledigt |
| Asset Browser (Stock-Fotos, Vektoren) | ✅ Erledigt |
| Video Browser | ✅ Erledigt |
| Connection Policy (Edge-Validierung) | ✅ Erledigt |
| Adjustment Presets (Built-in + User-defined) | ✅ Erledigt |
| Vollständige OpenRouter Image Gen (alle 9 Modelle + Tier-Enforcement) | ✅ Erledigt |
| Tier-aware Model Selector im Prompt-Node | ✅ Erledigt |
| Dashboard Snapshot Cache (gebündelte Query + localStorage) | ✅ Erledigt |
| Credits Activity Analytics (Recharts Chart) | ✅ Erledigt |
| Canvas Graph Query Cache (Performance-Optimierung) | ✅ Erledigt |
| AI Modularisierung (`ai_errors.ts`, `ai_retry.ts`, `ai_node_data.ts`) | ✅ Erledigt |
| docker-compose.yml + .env.example + Setup-README | ☐ Offen |

### Phase 2 — KI-Features

**Nodes:**
- Quelle: Farbe / Palette
- KI-Ausgabe: KI-Text, KI-Video
- Transformation: Crop / Resize, BG entfernen, Upscale
- Steuerung: Splitter, Loop, Agent
- Canvas & Layout: Text-Overlay

**Infrastruktur & Features:**

| Task | Status |
|------|--------|
| OpenRouter Text/Reasoning Integration (Claude 3.5 Sonnet) | ☐ Offen |
| Agent Node: Analyse, Clarification, Execution, Output | ☐ Offen |
| Skeleton-Nodes: Platzierung nach Plan-Erstellung | ☐ Offen |
| Browser Notifications API (opt-in, Tab-Wechsel) | ☐ Offen |
| Erster Agent Template: Instagram Curator | ☐ Offen |
| Self-hosted KI-Services (rembg, Real-ESRGAN) | ☐ Offen |
| Prompt-History und Re-Generation | ☐ Offen |
| Text-Overlay Node | ☐ Offen |

### Phase 3 — Kollaboration & Polish

**Nodes:**
- Transformation: Style Transfer, Gesicht (GFPGAN)
- Steuerung: Mixer, Weiche
- Canvas & Layout: Kommentar, Präsentation

**Infrastruktur & Features:**

| Task | Status |
|------|--------|
| Echtzeit-Kollaboration via Convex Subscriptions | ☐ Offen |
| Kommentar- und Annotations-System | ☐ Offen |
| Versions-History | ☐ Offen |
| Weitere Agent Templates | ☐ Offen |
| Export-Funktionen (PNG, PDF, ZIP) | ☐ Offen |
| Performance-Optimierung für große Canvases | ✅ Erledigt |

---

## 12. Offene Entscheidungen

| Thema | Entscheidung / Status |
|-------|----------------------|
| Authentifizierung | ✅ Better Auth (self-hosted, open-source) |
| Tailwind v4 | ✅ v4 ist Standard, keine Migration nötig |
| Pricing / Credit-System | ✅ Credit-Abstraktion (1 Cr = €0,01 intern), 4 Tiers, Reservation+Commit, Top-Up |
| Payment Provider | ✅ Polar (Merchant of Record, VAT-Handling) |
| Self-Hosting-Strategie | ✅ docker-compose.yml + .env.example + README |
| Convex Lock-in | ✅ Bewusst akzeptiert; Migrations-Pfad: Convex Cloud EU |
| OpenRouter Image-Modelle | ✅ Alle 9 Modelle aktiv mit serverseitigem Tier-Enforcement |
| Lizenz | ✅ BSL 1.1, 3 Jahre Change Date, Apache 2.0 |
| Repo-Strategie | ✅ Zwei unabhängige Repos, Auth-Cookie-Sharing |
| Job Queue | ✅ Convex native (Phase 1), externe Lösung bei Bedarf |
| E-Mail | ✅ Unsend + Stalwart, self-hosted |
| Analytics | ✅ Rybbit, self-hosted |
| Error Tracking | ✅ Sentry Cloud (Free Tier) |
| Cache-Strategie | ✅ Cloudflare (Edge) + Redis (Application) |
| E2E-Testing | ✅ Kein E2E in Phase 1 |
| UX-Latenzen | ✅ Node-Status-Modell, Skeleton-Nodes |
| Credit Fehlerbehandlung | ✅ Reservation + Commit |
| Bildbearbeitung: Rendering-Engine | ✅ WebGL + GLSL Shader als primäre Engine. WASM-Backend vorbereitet |
| Bildbearbeitung: Preset-Persistierung | ✅ User-Presets in Convex (`adjustmentPresets`-Tabelle) |
| Offline Sync | ✅ IndexedDB Queue + localStorage Cache + Optimistic Updates |
| Kollaborationstiefe | ⏳ Cursor-Sync, gleichzeitige Edits, Kommentare |
| Agent Clarification UX | ⏳ Inline am Node vs. Modal vs. Chat-Sidebar |
| Agent Template Format | ⏳ Markdown-Datei vs. strukturiertes JSON-Schema |
| Weiche: Bedingungslogik | ⏳ Visueller Rule-Builder vs. Ausdruckssprache |
| Mixer: Blend Modes | ⏳ min. Normal, Multiply, Screen, Overlay |
| Canvas-Export | ⏳ PNG, PDF, ZIP (Phase 3, Library TBD) |

---

## 13. Nicht-funktionale Anforderungen

| Anforderung | Beschreibung |
|-------------|--------------|
| Self-hostable | Vollständiger Betrieb auf eigenem VPS möglich; docker-compose.yml als primäres Deployment-Artefakt |
| Source Available | BSL 1.1 — Quellcode öffentlich, kommerzielle Nutzung lizenzpflichtig (siehe Abschnitt 15) |
| Performance | Canvas mit 100+ Nodes ohne spürbare Verzögerung |
| Datenschutz | Keine externen Tracking-Dienste; Ausnahme: Sentry Cloud für Error Tracking |
| Skalierbarkeit | Convex-Backend skaliert mit wachsender Nutzerzahl; Migrations-Pfad: Convex Cloud EU |
| Sicherheit | Rate Limiting auf allen API-Endpunkten via Redis, DDoS-Schutz via Cloudflare |
| UX-Resilienz | Alle KI-Operationen zeigen Status direkt am Node; Skeleton-Nodes bei Agent-Workflows |
| Credit-Integrität | Reservation+Commit-Mechanismus verhindert Credit-Verlust bei fehlgeschlagenen API-Calls |
| Offline-Fähigkeit | Canvas-Sync via IndexedDB Queue; Optimistic Updates mit ID-Remapping |

---

## 14. Nächste Schritte

1. docker-compose.yml + .env.example + Setup-README ausarbeiten
2. Vollständige OpenRouter Integration (alle 9 Modelle + Modellauswahl-UI)
3. Agent Node: Analyse, Clarification, Execution, Output
4. Self-hosted KI-Services (rembg, Real-ESRGAN, GFPGAN)
5. Transformation-Nodes (Crop/Resize, BG entfernen, Upscale)
6. Echtzeit-Kollaboration via Convex Subscriptions

---

## 15. Lizenzmodell

Die Software wird unter der Business Source License 1.1 (BSL 1.1) veröffentlicht. Der vollständige Quellcode ist öffentlich einsehbar, auditierbar und für private/persönliche Nutzung kostenlos. Kommerzielle Nutzung erfordert eine separate Lizenzvereinbarung.

### Parameter

| Parameter | Wert |
|-----------|------|
| Lizenz | Business Source License 1.1 |
| Change Date | 3 Jahre nach Veröffentlichung jedes Releases |
| Change License | Apache License 2.0 |
| Additional Use Grant | Nutzung ausschließlich für private und persönliche, nicht-kommerzielle Zwecke |

### Kommerzielle Lizenzen (geplant)

| Lizenz | Zielgruppe | Details |
|--------|------------|---------|
| Small Business | Unternehmen ≤ 10 Mitarbeiter | Preis und Konditionen TBD |
| Enterprise | Unternehmen > 10 Mitarbeiter | Preis und Konditionen TBD |
| OEM / Reseller | Einbettung in Drittprodukte | Individuelle Vereinbarung |

> **Positionierung:** LemonSpace wird als „Source Available" bzw. „Fair Source" positioniert — nicht als „Open Source" im Sinne der OSI-Definition. Der Quellcode ist vollständig öffentlich und transparent; Nutzungsrechte sind eingeschränkt bis zum Erreichen des Change Date.

---

*LemonSpace PRD v2.1 — April 2026*