cards/CLAUDE.md

# CLAUDE.md — cards repo

Guidance for Claude Code when working in this repository.

## 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.** Code dort wird gelesen
   (Lessons-Doc), nicht übernommen. Sauber neu ab Tag 0.
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`)