cards/CLAUDE.md

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. 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

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)