till/cards

Till JS 9a7068dd19 Phase 12 R0+R1: Marketplace-Restore-Plan + Schema in marketplace-pgSchema

R0 (Doku):
- Archiv unter docs/marketplace/archive/ aus managarten-Tag
  cards-decommission-base: MARKETPLACE_PLAN (654 Z., Vollvision mit
  mana-credits-Flow, Anti-Patterns), COMPETITORS, GUIDELINES,
  cards-server_CLAUDE.
- docs/playbooks/MARKETPLACE_RESTORE.md mit Schema-Naming-Entscheidung
  (eigenes marketplace-pgSchema), Wellen R0-R6, Cardecky-Skill-
  Integration, Lizenz-Modell.
- CLAUDE.md Invariante 2: Strategie-B gilt nur für Study-/FSRS-/Sync-
  Schicht; Marketplace-Restore ist explizite Ausnahme.
- STATUS.md: Phase 12 R0+R1 durch.

R1 (Schema):
- 16 Tabellen + 5 Enums im neuen marketplace-pgSchema (authors,
  decks, deck_versions, deck_cards, tag_definitions, deck_tags,
  deck_stars, deck_subscriptions, deck_forks, deck_pull_requests,
  card_discussions, deck_reports, ai_moderation_log, deck_purchases,
  author_payouts, author_follows).
- drizzle.config.ts: schemaFilter ['cards', 'marketplace'].
- Greenfield cards-pgSchema unangetastet.
- DB-CHECK decks_price_requires_license verifiziert (paid Deck mit
  CC-BY wirft sauber ab).
- type-check + 56 API-Tests grün, drizzle-kit push idempotent.

Decks dormant (kein Code-Pfad ruft die Tabellen). R2 (Backend α/β:
Author-Profile + Publish + AI-Mod) als nächstes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-09 15:05:22 +02:00

3.8 KiB

Raw Blame History

cards-server

Cardecky Marketplace + Community backend. Owns the published-deck side of the Cardecky product (the standalone app at cardecky.mana.how is the client). Phase α is the data skeleton — schema + bootstrap + JWT auth in place; routes land progressively in Phase β onwards.

For the full design rationale, phasing, and contract decisions see apps/cards/docs/MARKETPLACE_PLAN.md.

Tech Stack

Layer	Tech
Runtime	Bun
Framework	Hono
Database	PostgreSQL (`mana_platform.cards.*` schema) + Drizzle ORM
Auth	JWT via JWKS from mana-auth (EdDSA, jose)
Money	mana-credits — never Stripe directly

Port: 3072

Quick Start

# Schema push (writes to local mana_platform DB)
bun run db:push

# Dev server with watch
bun run dev

# Type check
bun run type-check

Database

Schema: cards inside the shared mana_platform DB. 17 tables across six logical groups (matching the source files in src/db/schema/):

File	Tables
`authors.ts`	`cards.authors`, `cards.author_follows`
`decks.ts`	`cards.decks`, `cards.deck_versions`, `cards.deck_cards`
`tags.ts`	`cards.tag_definitions`, `cards.deck_tags`
`engagement.ts`	`cards.deck_stars`, `cards.deck_subscriptions`, `cards.deck_forks`
`discussions.ts`	`cards.deck_pull_requests`, `cards.card_discussions`
`moderation.ts`	`cards.deck_reports`, `cards.ai_moderation_log`
`credits.ts`	`cards.deck_purchases`, `cards.author_payouts`

co_learn_sessions (Phase λ) is intentionally not yet in the schema. Every table is created via pgSchema('cards') per the Mana convention.

Auth model

Three middleware:

jwtAuth(authUrl) — validates Bearer tokens via JWKS. Sets c.set('user', { userId, email, role }). Used on every user-facing /v1/* route.
serviceAuth(serviceKey) — X-Service-Key check for service-to- service calls (e.g. mana-credits-webhook → cards-server).
(planned) optionalAuth — for routes that should respond differently when the caller is signed-in but never reject anonymous.

Phasing (per MARKETPLACE_PLAN §11)

Phase	What lands	Where
α	Skeleton + schema + JWT + health	now
β	Author publish flow + AI-mod-first-pass	next
γ	Discovery (browse, search, tags, follow)
δ	Subscribe + smart-merge
ε	Pull-requests + discussions
ζ	mana-credits marketplace
η	Moderation + trust
θ	Deep AI (auto-tags, embeddings, audio)
ι	Optimisation + scale

Environment Variables

PORT=3072
DATABASE_URL=postgresql://mana:devpassword@localhost:5432/mana_platform
MANA_AUTH_URL=http://localhost:3001
MANA_CREDITS_URL=http://localhost:3061
MANA_LLM_URL=http://localhost:3025
MANA_MEDIA_URL=http://localhost:3015
MANA_NOTIFY_URL=http://localhost:3040
MANA_SERVICE_KEY=dev-service-key
CORS_ORIGINS=http://localhost:5173,http://localhost:5180

# Author payout splits (basis points). Defaults: 80/20 standard,
# 90/10 verified-mana.
AUTHOR_PAYOUT_STANDARD_BPS=8000
AUTHOR_PAYOUT_VERIFIED_BPS=9000

# Community-verified auto-thresholds.
COMMUNITY_VERIFY_STARS=500
COMMUNITY_VERIFY_FEATURED=3
COMMUNITY_VERIFY_SUBSCRIBERS=200

Critical Rules

Never call Stripe directly. All money flows through mana-credits.
/v1 is the public contract — additive-only changes within v1, breaking changes go to /v2.
Content-hash everything. Per-card and per-version SHA-256s drive smart-merge, cache invalidation, and trust.
Subscribed Decks are unidirectional. Author → Subscriber. Forks for the bidirectional case.
Verification is binary, not numeric. Two flags (verified_mana, verified_community), the UI shows badges. Never invent a "trust score".

3.8 KiB Raw Blame History Unescape Escape