wordeck/CLAUDE.md

# 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:

0. **Text-only (ab Wordeck-Rebrand 2026-05-17).** Wordeck (vormals Cards)
   ist eine reine **Text-Karten-App**. CardTypes: `basic`, `basic-reverse`,
   `cloze`, `type-in`, `multiple-choice`. **Keine** `image-occlusion`,
   **kein** `audio`. Diese Invariante macht Offline-First, Sync und
   Inhaltspflege radikal einfacher. Migration: siehe
   [`mana/docs/playbooks/WORDECK_REBRAND.md`](../mana/docs/playbooks/WORDECK_REBRAND.md).
   Diese Datei wird erst nach Cutover endgültig durchgekämmt (Image-
   Occlusion-Verweise in §12 unten + Anki-Parser-Hinweise zu Media
   bleiben bis dahin als historischer Kontext).
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)
- `@mana/themes` (`^0.1.0`) — `forest`-Variant aus 12-Token-System
  (siehe `mana/docs/THEMING.md`); aktiviert via `data-theme="forest"`
  in `app.html` + `@import` in `app.css`
- `@mana/shared-ui-2` (`^0.1.0` seit 2026-05-09) — Greenfield-
  Komponenten mit strikter 12-Token-Disziplin. Cards konsumiert
  heute `PillTabGroup` (im Header für Routen-Nav + DE/EN-Switcher).
  Alte `@mana/shared-ui@0.1.x` aus den deps entfernt; Cards-Eigen-
  Komponenten (Modals, Marketplace-Cards etc.) bleiben bis weiterer
  Refactor-Sprint app-lokal.

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`)