Phase 0+1: Repo-Skelett für Cards-Greenfield

Strategie B (beschlossen 2026-05-08): Cards wird als eigenständige föderierte App neu gebaut, ohne Code-Übernahme aus mana-monorepo. Skelett enthält: - apps/api: Hono+Bun mit /healthz, /version, Manifest-Endpoint, leere pgSchema('cards'), Drizzle-Config, erstem Vitest - apps/web: SvelteKit 2 + Svelte 5 (runes), Vite auf 3082 - packages/cards-domain: Pure-TS, CardType-Discriminated-Union, SubIndex-Granularität für Reviews, Future-CardType-Set vorbereitet - infrastructure/docker-compose.yml: Postgres 16 auf 5435 - app-manifest.json: v1.0.0, Verein-owned, beta-tier - .github/workflows/ci.yml - docs/LESSONS_FROM_MANA_MONOREPO.md (Read-Day-Output, 15 Lehren) Pre-Flight für Phase 2 (Auth-Föderation): DNS cardecky.mana.how, GitHub-Repo mana-ev/cards, Cards-App-Registrierung in mana-auth, NPM_AUTH_TOKEN für Verdaccio. Plan: mana/docs/playbooks/CARDS_GREENFIELD.md Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-08 14:08:41 +02:00 · 2026-05-08 14:08:41 +02:00 · 8605b1b517
commit 8605b1b517
37 changed files with 1197 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -0,0 +1,133 @@
+# 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`)