d7f3b93996
Some checks are pending
CI / validate (push) Waiting to run
@mana/shared-ui-2@0.1.0 wurde heute publiziert. Cards' einziger shared-ui-Konsument war PillTabGroup im Header (Routen-Nav + DE/EN-Switcher). Drop-in-Migration: - apps/web/package.json: @mana/shared-ui + @mana/shared-icons raus (letzteres war nur shared-ui-Transitive, in Cards-Code nirgends direkt importiert), @mana/shared-ui-2 ^0.1.0 rein. - Header.svelte: Import wechselt von @mana/shared-ui auf @mana/shared-ui-2. primaryColor-Prop entfernt — shared-ui-2 PillTabGroup nutzt --color-primary direkt aus dem 12-Token-Set. Bridge-Aliase in app.css bleiben — Cards' Eigen-Komponenten (Header-Logo, Modals, Marketplace, Routen) nutzen historisch --color-card, --color-popover, --color-accent etc. Diese Tokens existieren im 12-Token-Mana-Set NICHT, aber die Aliase mappen sie weiter aufs 12er-Set. Aliase-Kommentar präzisiert: nicht mehr für shared-ui@0.1.x (raus), sondern für Cards-eigenen Code, bis Cards in eigenem Refactor-Sprint auf das 12er-Vokabular umzieht. Type-check-Pipeline schrumpft drastisch: von 3994 Files (mit shared-ui@0.1.x's 176 Quellfiles + transitive) auf 439 Files (nur Cards + shared-ui-2's kleinerer Surface). Build sauber, weniger JS im Output-Bundle. Cards ist damit die erste Vereins-App, die operativ auf shared-ui-2 läuft — End-to-End-Beweis dass das System trägt. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
156 lines
6.9 KiB
Markdown
156 lines
6.9 KiB
Markdown
# 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)
|
|
- `@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`)
|