till/cards
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
cards/CLAUDE.md
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

6.4 KiB
Raw Blame History

CLAUDE.md — cards repo

Guidance for Claude Code when working in this repository.

Wenn du gerade neu bist: lies zuerst STATUS.md — dort steht der aktuelle Phasen-Stand, was schon läuft, was offen ist, und wie du lokal verifizierst. Dieses CLAUDE.md ist nur die Konventions- und Architektur-Referenz; der Status lebt in STATUS.md, damit er nicht zwischen mehreren Dateien drifted.

Was dieses Repo ist

Cards — eigenständige föderierte Spaced-Repetition-App des Vereins mana e.V. Greenfield-Build (Strategie B, beschlossen 2026-05-08). Cards ist eine Peer-App im mana-Ökosystem: redet über mana-share/-mcp/-search/-events/-credits mit Memoro, Who und der Mana-Successor-App, hat aber eigene DB, eigenes Frontend, eigene Deployment-Pipeline.

                  HTTP/JWT      ┌──────────────┐
   mana e.V.   ◄─────────────── │  cards/      │  Postgres `cards`
   Plattform                    │  (this repo) │  cardecky.mana.how
   (auth/credits/share/etc.)    └──────────────┘

Status

Phase 0 — Repo-Skeleton. Vollständiger Plan in mana/docs/playbooks/CARDS_GREENFIELD.md (im Plattform-Repo). Nächste konkrete Schritte: Read-Day, dann Phase 1 (Auth-Föderation).

Konventionen

  • pnpm 9.15.x, Node 20+, Turborepo 2.x
  • Tabs für Indent, single quotes, 100-col Prettier (.prettierrc.json ist die Source of Truth)
  • Stack: SvelteKit 2 + Svelte 5 (runes-only) für Web, Hono + Bun + Drizzle für API, Postgres mit pgSchema('cards')
  • Drizzle 0.38 / drizzle-kit 0.30 / zod 3 — bewusst gleich wie mana-Plattform; Migration auf 0.45/0.31/zod-4 läuft mit Plattform- Migrations-Pfad mit (mana/docs/MIGRATION_DRIZZLE_ZOD.md)
  • JWT-Validation lokal via JWKS-Cache (5 min), niemals Live-Call zu mana-auth pro Request
  • Service-to-Service-Calls via X-Service-Key (CARDS_APP_SERVICE_KEY) oder mana-auth-issued Bearer-Tokens
  • Tests: Vitest für Unit/Integration, Playwright für e2e
  • Formatierung: pnpm run format vor jedem Commit

Architektonische Invarianten

Diese sind beschlossen. Nicht ohne explizite Diskussion antasten:

  1. Server-authoritative MVP. Keine Dexie, keine IndexedDB, keine eigene Sync-Engine. Frontend = HTTP-Client zu cards-api. Local-First später via mana-sync-Federation, nicht durch eigenen Stack.
  2. Kein Code aus mana-monorepo kopiert — für die Study-/FSRS-/Sync- Schicht. Diese Architektur (Server-authoritative, kein Dexie, neue Type-Hierarchie) ist sauber neu ab Tag 0. Ausnahme: Marketplace- Restore. Der ehemalige services/cards-server/ aus mana-monorepo war nie auf der Strategie-B-Verbots-Liste — er wurde am 2026-05-08 nur mit-rausgerissen, weil er an apps/cards/ gekoppelt war. Bei einem Restore wird der Marketplace-Code aus dem cards-decommission-base-Tag im managarten-Repo additiv re-import'd, in eigenes marketplace-pgSchema, additiv zur Study-Welt. Plan: docs/playbooks/MARKETPLACE_RESTORE.md.
  3. Eigene Postgres-DB cards im geteilten Mana-Cluster, Schema- Isolation via pgSchema('cards').
  4. Föderation über @mana/shared-app-tpl. Pflicht-Endpoints (/.well-known/mana-app.json, /healthz, /api/v1/share/receive, /api/v1/tools/:name, /api/v1/search, /api/v1/dsgvo/...) kommen aus dem geteilten Boilerplate.
  5. Keine externe SaaS, wo vermeidbar. Erlaubte Ausnahmen kommen über mana-Plattform: Stripe (mana-credits), Anthropic/OpenAI (mana-llm), Cloudflare-Tunnel (Edge-Routing).
  6. Encryption initial AUS. Nachrüstbar, wenn sensibles Feld auftaucht.

Repo-Struktur

cards/
├── apps/
│   ├── web/                  SvelteKit-Frontend (cardecky.mana.how)
│   └── api/                  Hono+Bun-Backend
├── packages/
│   └── cards-domain/         Pure-TS: FSRS, Card-Types, Schemas, Anki-Parser
├── infrastructure/           docker-compose, tunnel-config
├── docs/                     DOMAIN.md, ANKI_IMPORT.md, LESSONS_FROM_MANA_MONOREPO.md, …
├── app-manifest.json         Source of Truth für Föderation
└── .github/workflows/        ci.yml, deploy.yml

@mana/* Konsumation

Cards zieht alle Shared-Pakete aus Verdaccio (pkg.mana.how):

  • @mana/shared-share-protocol — Manifest, Envelope-Schemas
  • @mana/shared-app-tpl — Pflicht-Endpoint-Boilerplate
  • @mana/shared-hono — Auth-Middleware, Health-Routes, Error-Handler
  • @mana/shared-auth — Client-SDK für Login-Flow
  • @mana/shared-types — Common Types
  • @mana/shared-icons, @mana/shared-i18n, @mana/shared-theme, @mana/shared-tailwind — UI-Building-Blocks (kein Code-Duplikat aus mana-monorepo)

Alle als reguläre dependencies. Versions-Disziplin ist Klasse-A (siehe mana/docs/SHARED_PACKAGES.md).

Wichtige Cross-Repo-Doks

  • mana/docs/playbooks/CARDS_GREENFIELD.md — der vollständige Plan
  • mana/docs/FEDERATION.md — Architektur-Grundlagen
  • mana/docs/SHARE_PROTOCOL.md — Manifest- und Envelope-Schemas
  • mana/docs/MANA_AUTH_FEDERATION.md — App-Identitäts-Modell
  • mana/docs/SHARED_PACKAGES.md — Versionierungs-Disziplin
  • mana/docs/PORTS.md — Port-Allokation (cards-api: TBD, cards-web: TBD)

Wenn ein neuer Pflicht-Endpoint dazukommt

  1. app-manifest.json aktualisieren (Endpoint-Pfad, Auth-Mode)
  2. Handler in apps/api/src/routes/ schreiben
  3. Tests in apps/api/tests/ (Vitest)
  4. pnpm run validate:manifest lokal grün
  5. CI-Workflow zieht Manifest-Validation automatisch

Wenn ein neues Tool/Share/Accept dazukommt

  1. Schema in packages/cards-domain/src/schemas/ definieren (zod)
  2. JSON-Schema-Export für mana-mcp/mana-share generieren
  3. Handler im Manifest registrieren (tools[].name oder accepts[].handler)
  4. Implementierung in apps/api/src/routes/tools.ts bzw. apps/api/src/share-handlers/
  5. Test-Coverage: zod-parse + Handler-Logic getrennt

Lokal entwickeln

pnpm install                  # @mana/* aus pkg.mana.how holen
pnpm docker:up                # Lokales Postgres
pnpm db:push                  # Drizzle-Schema aktualisieren
pnpm dev                      # api + web parallel

Voraussetzungen:

  • mana-Plattform-Stack lokal laufend (mana-auth, optional die Föderations-Services für E2E-Tests)
  • Verdaccio-Token in ~/.npmrc (npm login --registry=https://pkg.mana.how)