cards/docs/playbooks/MARKETPLACE_RESTORE.md

Marketplace-Restore — Playbook

Status: Plan, R0+R1 in Arbeit. Stand 2026-05-09. Vorgänger: das alte services/cards-server/ aus managarten/ (mana- monorepo) wurde am 2026-05-08 zusammen mit apps/cards/ dekommissioniert, weil beides eine Kopplung war — siehe Decommission-Commits bc158cb0b (cards-server), 9cd871749 (apps/cards), dd1bab09d (cards-core). Rollback-Tag: cards-decommission-base im managarten-Repo.

Dieser Plan dokumentiert den Restore des Marketplace-Backends in die Standalone-Cards-App, additiv zur bestehenden Greenfield-API.

TL;DR

• Strategie-B-Klarstellung: „Kein Code aus mana-monorepo" galt der Study-/FSRS-/Sync-Schicht (Dexie raus, server-authoritative). Marketplace war nie davon betroffen — er wurde nur mit-rausgerissen, weil er an apps/cards gekoppelt war.
• Restore vs. Neubau: Restore. ~13.000 Zeilen reifer Code, 8 Phasen in Produktion gelaufen, Plan-Doku in Goldstandard-Qualität (654 Zeilen), bekannte Limitierungen sauber dokumentiert. Neubau wäre 4–6 Wochen, Restore ~14 Tage.
• Schema-Naming-Entscheidung: Eigenes marketplace-pgSchema in derselben cards-DB. Begründung: saubere Read/Write-Trennung, Backup-Granularität (pg_dump --schema=marketplace), RLS-Policies pro Schema möglich, keine Kollisionen mit den existierenden cards.{decks,cards,reviews,…}-Tabellen.
• Service-Topologie: Single-Service. Marketplace-Routen kommen unter /api/v1/marketplace/* in den bestehenden cards/apps/api. Kein zweiter Hono-Prozess, kein zweiter Container. YAGNI bei deinem Volumen.
• Frontend: alte Routes 1:1 nach cards/apps/web/src/routes/ — /explore, /d/[slug], /u/[slug], /me/{published,subscribed,forks,purchases}, /admin/reports. Imports auf Verdaccio-Pakete umstellen, Theming- Bridge-Aliase greifen automatisch.
• Restore-Reihenfolge: R0 (Doku) → R1 (Schema) → R2 (Auth + Routes α/β) → R3 (γ + δ) → R4 (ε) → R5 (Frontend) → R6 (Smoke + erste Cardecky-Decks publishen).
• Was nicht im ersten Wurf: Paid Decks (ζ.1) und Moderation-UI (η.1). Schema-Tabellen kommen mit, aber Code-Pfade bleiben dormant bis nach erstem Live-Test.

---

Was die alte Implementation konnte (Phase α–η.1)

Inhalt der archivierten Dokumente — Original-Wahrheit unter cards/docs/marketplace/archive/:

Datei	Was drin
MARKETPLACE_PLAN_2026-05-07.md	654-Zeilen-Vollvision: Datenmodell, mana-credits-Flow, Cold-Start-Strategie, Anti-Patterns, Phasen-Status
COMPETITORS_2026-05.md	353-Zeilen-Konkurrenz-Analyse: Quizlet, AnkiHub, Brainscape, AnkiPro, AnkiApp, RemNote, Mnemosyne
GUIDELINES.md	367 Zeilen Community-Guidelines + Lizenz-Modell (SPDX + Cardecky-Personal-Use-1.0 + Cardecky-Pro-Only-1.0)
cards-server_CLAUDE.md	110 Zeilen Tech-Stack-Doku des Original-Service

Phasen-Status zum Zeitpunkt der Decommission (2026-05-08):

Phase	Status	Was lief produktiv
α — Skelett	✅ live	17-Tabellen-Schema, JWT-Auth, Container, Tunnel cardecky-api.mana.how
β — Author-Workflow	✅ live	Profil-Claim, Publish, Lizenz-Picker (SPDX), Preis-Eingabe, AI-Mod-First-Pass
γ — Discovery	✅ live	/explore, Stars, Follows, Author-Profile, Trending, Search (ILIKE)
δ — Subscribe + Smart-Merge	✅ live	Pull, Diff-View „+N · ~N · −N", FSRS-State erhalten über Karten-Hash-Diff
ε — PRs + Discussions	✅ live	„✏️ Verbessern" auf jeder Karte, Author-Merge, Inline-Threads, Notify-Mails
ζ.1 — Paid Decks	✅ live	4-Schritt-Reserve→Purchase→Commit→Grant, 80/20-Split (90/10 für verified_mana)
η.1 — Moderation	✅ live	Reports, Admin-Inbox, Takedown-Workflow (kaskadiert auf PRs), Author-Ban

Bekannte Limitierungen (siehe MARKETPLACE_PLAN_2026-05-07.md §13a): PR-Merge-stale-blind, Reconciler-Lücke bei Paid-Pipeline, Mention-System fehlt, Discussion-Threading 1-Level, kein Refund-Self-Service. Alles dokumentiert, nichts unbekannt.

---

Architektur-Anpassungen für den Restore

1. DB-Topologie: eigenes marketplace-pgSchema

Alt (in mana_platform-DB, geteilt mit allen mana-Services):

mana_platform.cards.{authors, decks, deck_versions, …}        — 17 Tabellen

Neu (in standalone cards-DB des Standalone-Repos):

cards.cards.{decks, cards, reviews, media_files, tags, imports}  — Greenfield, bleibt
cards.marketplace.{authors, decks, deck_versions, deck_cards, …} — Restore, neu

Begründung für ein eigenes pgSchema statt Tabellen-Prefix (published_decks, published_deck_versions, …):

• Sauberer Read-Path. Public-Endpoints sehen nur das marketplace- Schema. Greenfield-Code (private Decks/Karten/Reviews) sieht ausschließlich cards. Kein Risiko, dass ein SELECT * FROM decks versehentlich beide Welten mischt.
• Backup-Granularität. pg_dump --schema=marketplace exportiert nur den Marketplace-Stand für Compliance/Recovery. Privater Lern- Stand der User bleibt unangetastet.
• RLS-Policies pro Schema — falls wir je Row-Level-Security einführen für public-decks-take-down-Workflows, ist das pro Schema konfigurierbar.
• Drizzle-kit-Push-Disziplin. schemaFilter: ['cards', 'marketplace'] hält beide Pushes sauber. Schema-Drift fängt sich auf Schema-Ebene.

Drizzle-Variablennamen halten den public-Prefix aus dem alten Code: publicDecks, publicDeckVersions, publicDeckCards. So bleibt das intent klar, und Imports kollidieren nicht mit cards.decks aus dem Greenfield.

2. Auth-Modell: identisch, kein Refactor

Alter cards-server: JWKS-Cache gegen mana-auth. Greenfield-cards-api: JWKS-Cache gegen mana-auth. Identisch. Service-Key-Auth (X-Service-Key) für Mana-Webhooks ebenfalls 1:1 übernommen.

Optional-Auth-Middleware für Public-Endpoints (/explore, /d/:slug) muss aus dem alten Code mitkommen — der erlaubt anonymen Read und gibt zugleich personalisierte Daten (z.B. „Bist du Subscriber?") wenn ein Bearer mit-übermittelt ist.

3. Service-Topologie: Single-Service

Alle Marketplace-Routen unter /api/v1/marketplace/* in cards/apps/api/src/routes/marketplace/:

cards/apps/api/src/routes/marketplace/
├── authors.ts
├── decks.ts            (publish, list, version reads)
├── engagement.ts       (stars, subscribe, fork)
├── discussions.ts      (card-discussions threads)
├── pull-requests.ts
├── moderation.ts       (reports + admin)
├── purchases.ts        (paid decks — dormant in R3, aktiv ab späterer Welle)
└── explore.ts          (discovery + search)

Hauptserver-Mount in cards/apps/api/src/index.ts:

app.route('/api/v1/marketplace/authors', authorsRouter())
app.route('/api/v1/marketplace/decks', decksRouter())
// …

Vorteile: ein Prozess, ein Container, ein Tunnel-Endpoint (cardecky-api.mana.how), eine JWT-Validierung, eine Drizzle-DB-Connection.

4. Frontend: additive Routes, gleicher Stack

cards/apps/web/ ist SvelteKit + Svelte 5 (runes-only). Alter apps/cards/apps/web/ war es auch. Routen werden 1:1 übernommen, mit drei Anpassungen:

• Imports: @mana/shared-* kommt heute aus Verdaccio (npm.mana.how). pnpm add @mana/shared-ui@^0.1.1 @mana/shared-share-protocol ….
• Theming: alte Components nutzten alte Token. Greenfield-Bridge- Aliase in app.css mappen die meisten alten Token aufs 12er-Mana- Vokabular. Test im Browser, ggf. Anpassungen.
• Auth-Hook: dev-stub.svelte.ts bleibt für Phase-2-Lücke. Sobald echte mana-auth-Login-Flow ausgerollt ist (siehe STATUS.md), weicht der Stub für @mana/shared-auth.

5. Hash-Implementierung: bestehende @cards/domain benutzen

Alter cards-server/src/lib/hash.ts: eigenständige SHA-256-Implementierung. Greenfield: cardContentHash in @cards/domain (Web-Crypto, deterministisch).

Beim Restore: lib/hash.ts nicht mit-übernehmen, sondern Marketplace-Code auf cardContentHash aus @cards/domain umbiegen. Eine Hash-Definition für die ganze App.

6. mana-Service-Calls: identische Pattern

Alter cards-server rief mana-credits, mana-llm, mana-media, mana-notify über MANA_*_URL-env-Vars. Greenfield-cards-api macht das genauso. Code 1:1 übernehmen.

---

Wellen-Plan

Welle	Zustand	Was passiert	Blocker
R0	🟡 in Arbeit	Doku-Restore: Archive aus cards-decommission-base + dieser Plan + Strategie-B-Klarstellung	—
R1	⏸ pending	Schema-Restore: 7 Schema-Files in cards/apps/api/src/db/schema/marketplace/, drizzle-kit push grün gegen lokale cards-DB	R0
R2	⏸ pending	Backend Phase α + β: Author-Profile + Publish + AI-Mod-Stub	R1
R3	⏸ pending	Backend Phase γ + δ: Discovery + Subscribe + Smart-Merge	R2
R4	⏸ pending	Backend Phase ε: Pull-Requests + Card-Discussions	R3
R5	⏸ pending	Frontend-Routes: /explore, /d/[slug], /u/[slug], /me/{published,subscribed,forks}	R4
R6	⏸ pending	E2E-Smoke: erstes Cardecky-Deck publishen, von Till's Account subscriben, Smart-Merge testen	R5

Aufwand-Schätzung gesamt: ~14 Tage Real-Arbeit.

Bewusst aus dem ersten Restore-Wurf rausgelassen:

• ζ.1 Paid Decks — Schema-Tabellen kommen in R1 mit, aber Routes/UI bleiben dormant. Re-Aktivierung als eigene Welle nach Live-Validation. Begründung: mana-credits-Integration ist heikel (4-step-Pipeline mit reservation-commit-grant), Author-Erlöse sind ein Verein-Compliance- Thema (Steuern, AGB, Refund-Policy), und solange Cardecky synthetic Decks publisht, gibt's keinen Need.
• η.1 Moderation-UI — Schema-Tabellen + API-Endpoints kommen mit, Admin-Frontend (/admin/reports) wird ausgelassen bis erste echte User da sind. Take-Down via SQL für die ersten Wochen.
• θ Deep AI (Auto-Tags, Embeddings, TTS) — bleibt explizit später- Phase, war im Original-Plan auch nicht für den ersten Wurf vorgesehen.

---

Cardecky-Skill-Integration

Der /cards-deck-Skill (siehe ~/.claude/skills/cards-deck/SKILL.md) produziert Decks unter dem Cardecky-Plattform-User. Beim Marketplace- Restore wird Cardecky automatisch zum Marketplace-Author:

1. Bei R2 wird ein Init-Skript einen marketplace.authors-Row für Cardecky-User-ID anlegen (slug='cardecky', display_name='Cardecky', pseudonym=false, verified_mana=true — der Verein vergibt das Badge an seinen eigenen KI-Author).
2. Skill-Stufe 5 (Publish) wird erweitert um einen optionalen Schritt: nach Anlegen des privaten Decks kann der Skill ein POST /api/v1/marketplace/decks/:id/publish mit semver=1.0.0 und einem auto-generierten Changelog hinterher schicken — dann ist das Deck sofort im /explore sichtbar.
3. Default bleibt aber „nur privat anlegen", weil:
   • das Validate-Stage (Stufe 4) eine menschliche Sichtung verdient, bevor 30 Karten öffentlich werden;
   • Reviewer-Stops nach Stufe 3 sind zwingend.

Der Skill braucht keine Architektur-Änderung — er addiert nur einen optionalen 6. Schritt.

---

Lizenz-Modell (aus dem Original übernommen)

Aus MARKETPLACE_PLAN_2026-05-07.md §3 + GUIDELINES.md:

SPDX-ID	Erlaubt	Wann
CC0-1.0	alles, kein Attribution-Pflicht	für Public-Domain-fähige Karten
CC-BY-4.0	alles, mit Attribution	meist gewählt für Wissens-Decks
CC-BY-SA-4.0	alles, ShareAlike + Attribution	für Wikipedia-derivierte Decks
Cardecky-Personal-Use-1.0	nur persönlicher Lern-Use, kein Re-Publish	Default für kostenlose Decks
Cardecky-Pro-Only-1.0	nur via Kauf, kein Re-Publish, kein Fork	Pflicht für paid Decks (DB-CHECK enforced)

Der DB-CHECK auf decks.price_credits = 0 OR license = 'Cardecky-Pro-Only-1.0' ist im Schema beibehalten — Code-Bug kann nicht stillschweigend ein Paid-Deck mit CC-Lizenz publishen.

---

Cold-Start-Strategie (aus dem Original)

Kommt im ersten Restore-Wurf nicht aktiv zum Tragen, aber der Original- Plan §9 hat drei Hebel definiert, die bei Re-Launch greifen:

1. Verein-Seed-Decks — 50 hochwertige Cardecky-published Decks (Sprachen, Geschichte, Allgemeinwissen, Programmierung). Der /cards-deck-Skill ist genau das Werkzeug dafür.
2. Anki-Top-100-Import-Service — populäre CC-BY-Anki-Decks mit Original-Author-Attribution importieren, Original-Author bekommt verified_mana-Badge bei Registrierung.
3. Influencer-Outreach — 10–20 Anki-Power-Authoren (AnKing & Konsorten) gezielt ansprechen, sehr Author-freundlicher Cut.

Hebel 2 + 3 sind Wachstumsmaßnahmen, nicht Phase-1. Hebel 1 ist sofort umsetzbar mit dem bestehenden Skill.

---

Anti-Patterns aus dem Original-Plan §13 (gelten weiter)

• Kein 1-5-Sterne-Rating-System. Stars (Bookmark) ja, Bewertungen nein.
• Kein Reddit-Style-Voting auf Karten/PRs/Discussions. Hacker-News-Effekt.
• Kein „Karten der Woche" allein-algorithmisch. Editorial + Trending- Liste, aber niemals reiner Algo-Feed.
• Kein Anki-Bashing im Marketing. Bridge nicht Burning.
• Keine Pflicht-Klarnamen. Pseudonyme bleiben gleichberechtigt.
• Kein Marketplace-Cut über 30 %. Standard 80/20, verified 90/10.

---

Offene Punkte

• PR-Merge-stale-blind aus dem Original. Bekannte Limitierung: wenn Author zwischen PR-Open und Merge selbst eine Karte ändert, deren previousContentHash der PR matched, gewinnt stumm der PR. Im ersten Restore-Wurf so übernehmen wie war; späterer Fix via optimistic locking auf baseVersionId der PR-Row mit Reject bei Mismatch.
• Reconciler-Cron für Paid-Pipeline-Inkonsistenzen. Original §13a beschreibt das Loch: bei Commit-/Grant-Failure nach Schritt 2 bleibt eine Purchase-Row mit creditsTransaction = null. Beim Restore initial nicht aktiv (Paid-Decks dormant), aber sobald Phase ζ reaktiviert wird, ist Reconciler ein muss-haben.
• cards-decommission-base-Tag im managarten-Repo. Falls jemand managarten löscht oder das Tag nochmal entfernt, geht der Restore- Pfad verloren. Empfehlung: Schema-Files + ausgewählte Code-Snippets einmal nach cards/docs/marketplace/archive/ kopieren (Doks sind schon drin, Code-Files folgen optional bei R1+R2).
• Schema-Migrations-Pfad bei späterer Drizzle-Version. Greenfield- Cards plant Migration auf Drizzle 0.45/zod-4 mit der Plattform mit (mana/docs/MIGRATION_DRIZZLE_ZOD.md). Marketplace-Schema kommt mit Drizzle 0.38 — sollte mit upgradeen, idealerweise atomar.
• Karten-Hash-Konsistenz zwischen Greenfield und Marketplace. Greenfield-@cards/domain cardContentHash ist die SoT. Marketplace- deck_cards.content_hash muss mit demselben Algorithmus berechnet werden — sonst funktioniert Smart-Merge nicht. Beim R2-Port-Pass testen, dass cardContentHash({type,fields}) aus @cards/domain byte-identisch ist mit dem alten cards-server/src/lib/hash.ts. Wenn nicht: alten Code anpassen, nicht @cards/domain brechen.