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

147 lines
6.4 KiB
Markdown
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`](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`](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
```bash
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`)
Reference in a new issue View git blame Copy permalink