2bed28212d
Bisherige Doku war über CLAUDE.md, README.md, SMOKE_TEST.md, LESSONS_FROM_MANA_MONOREPO.md plus mana/docs/playbooks/CARDS_GREENFIELD.md zerstreut — eine fresh-AI-Session musste sich Status zusammenstückeln. STATUS.md zentralisiert: - TL;DR + Architektur-Topologie - Architektur-Entscheidungen (festgenagelt) - Phasen-Status-Tabelle (✅/🚧/⏸ pro Phase mit Verifikations-Hinweis) - Lokal-Lauf-Anleitung (5 Schritte zu cards-api + cards-web im Browser) - Verifizierte Endpoints-Liste - Pre-Flight für Phase 2 + Live-Föderation - Wichtige Pointer: Konventionen, Stack, Files, Cross-Repo-Doks - Git-Historie (6 Commits) - 6 Architektur-Subtilitäten, die nicht offensichtlich sind: Reviews-plaintext, SubIndex-Granularität, Protocol-Mirror-TEMPORARY, Inbox-Auto-Create, Dev-Auth-temporär, mana-monorepo-Decommission - Onboarding-Sequenz (5-Min-Lese-Plan) - Vorschläge für nächste Phasen Cross-References: - CLAUDE.md verweist als erstes auf STATUS.md - README.md ebenso - mana/docs/playbooks/CARDS_GREENFIELD.md (im Plattform-Repo) verweist zurück auf cards/STATUS.md für aktuellen Stand — Playbook ist der Plan, STATUS.md ist die Lage. Konvention: bei Phasen-Wechsel STATUS.md aktualisieren, nicht den Playbook (sonst Doku-Drift). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
139 lines
5.9 KiB
Markdown
139 lines
5.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.** 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`)
|