zitare-native/CLAUDE.md

CLAUDE.md — zitare-native repo

Guidance für Claude Code in diesem Repository.

Wenn du gerade neu bist: lies zuerst PLAN.md und docs/NATIVE_LIFT_PLAN.md. Das ältere Hybrid-Playbook in ../mana/docs/playbooks/ZITARE_NATIVE_GREENFIELD.md ist seit 2026-05-22 überholt — nur als historische Referenz lesen.

Was dieses Repo ist

Zitare Native — native SwiftUI-Universal-App (iOS / iPadOS / macOS) für Zitare, den öffentlichen Zitat-Korpus des Vereins mana e.V.

                       HTTPS         ┌──────────────────┐
   zitare.com         ◄────────────  │ zitare-native    │  pure SwiftUI
   (Snapshot + AASA)                 │ (this repo)      │  SwiftData (voller Korpus)
                                     │ ev.mana.zitare   │  WidgetKit + ShareExt + Spotlight
   api.zitare.com    ◄────────────   │                  │  SafariView (nur Legal)
   (Read + Submit)                   │                  │
                                     └──────────────────┘

Status

Phase η-0 — De-Hybrid (2026-05-22, in Arbeit). Hybrid-Strategie (WKWebView für Read-Surfaces) wurde aufgegeben. Plan + Phasen-Übersicht in docs/NATIVE_LIFT_PLAN.md. Status-Spur in PLAN.md.

Leitprinzip: pure-native + Offline-first

Das Verteilungs-USP-Argument trägt allein nicht; die App soll auch Funktion + Lese-Komfort eigenständig liefern, ohne den Browser-Schwester- Pfad. Native bringt:

1. Voller Korpus offline in SwiftData (Snapshot-Sync index-full.json).
2. Lokale FTS + Server-Fallback bei seltenen Queries.
3. Home-Screen-Widget „Zitat des Tages".
4. ShareExtension als Ziel für markierten Text.
5. Spotlight-Index für system-weite Volltext-Suche.
6. Native Submit mit ManaAuthUI.
7. SafariView nur für statische Verein-Recht-Seiten (Impressum, Datenschutz, Lizenz) — kein WKWebView im Binary.

Architektonische Invarianten (η)

Beschlossen 2026-05-22. Nicht ohne explizite Diskussion antasten.

1. Pure SwiftUI für alle Surfaces. Kein WKWebView im App-Binary. ManaWebShell-Dep ist raus aus project.yml.
2. Offline-first Lesen. SwiftData ist Primary-Store, API ist Fallback bei Cache-Miss + Sync-Quelle. Flugmodus-Test ist Akzeptanz- Kriterium ab η-2.
3. Quote-Korpus ist Snapshot. Beim Launch + Background-Refresh wird index-full.json gepullt, ETag-aware, in SwiftData persistiert, per App-Group an Widget + ShareExt + Spotlight durchgereicht.
4. Server gewinnt bei Schema-Konflikt. SwiftData-Modelle sind eine abgeleitete Spiegelung des Drizzle-Schemas in zitare/apps/api/.
5. Search lokal-first. Lokale FTS aus SwiftData; bei < 3 Treffern oder leerem Result Server-Fallback (GET /api/v1/quotes?q=).
6. Legal-Seiten via SafariView. Impressum / Datenschutz / Lizenz öffnen SFSafariViewController. Das ist die einzige zugelassene Browser-Brücke und nur für statisches Verein-Recht-Material.
7. Schreiben bleibt Submit-only in v1. Edit / Moderation / Flags- Verwaltung kommen NICHT in die App — bleiben Web.
8. Universal-Links auf zitare.com lösen ins native Surface. AASA bleibt, onContinueUserActivity routet auf SwiftUI-Views, nicht in einen WebView-Tab.
9. mana-auth via ManaCore + ManaAuthUI. Submit + Konto nutzen AuthClient und die fertigen Views aus ManaAuthUI. Keine eigene Auth, keine Cookie-Bridge mehr (entfällt mit WKWebView).
10. Universal-Link-Domain: zitare.com (+ app.zitare.com als AASA-Redundanz). AASA auf https://zitare.com/.well-known/apple-app-site-association.
11. Theme: paper-Variant default. Werte aus @mana/themes/paper, lokal als ZitareTheme.swift nachgebaut.
12. Bundle-ID ev.mana.zitare. Reverse-Domain mana-ev.ch. App-Display-Name: „Zitare". Category: public.app-category.reference.
13. Web gewinnt bei Konflikt im Datenmodell. Funktion wandert zuerst in zitare/apps/zitare/ oder zitare/apps/api/, dann ins native Surface hier — kein einseitiger Native-Vorlauf, der das Web abhängt.

Konventionen

• Swift 6.0, Strict Concurrency komplett
• iOS 18 / iPadOS 18 / macOS 15 Minimum
• SwiftUI als einziges UI-Framework, WKWebView via UIViewRepresentable/NSViewRepresentable die einzige Bridge
• XcodeGen als SOT: project.yml definiert Targets, Info.plist, Entitlements. .xcodeproj, generierte Info.plist und Entitlements sind nicht im Git
• SwiftFormat mit .swiftformat
• SwiftLint mit .swiftlint.yml
• Logging: App-Subsystem ev.mana.zitare via Sources/Core/Telemetry/Log.swift
• Persistenz: SwiftData für Snapshot-Cache + PendingSubmission- Queue, JWT im Keychain (über ManaCore)
• Lokalisierung: DE primary, EN fallback via Localizable.xcstrings

Zitare-API-Wire-Format

Wire-Format gegen https://zitare-api.mana.how/api/v1/*. Quelle der Wahrheit: ../zitare/apps/api/src/routes/*.ts. Bei neuem DTO:

1. Path + Method gegen den Hono-Handler prüfen
2. Response-Schema (zod) gegen Codable-Struct mappen
3. snake_case via CodingKeys, optionale Felder explizit Optional<T>
4. Test-Fixture aus echtem Server-Response in Tests/UnitTests/

Snapshot-Vertrag

https://zitare.com/index-min.json ist der lokale Korpus-Spiegel. Heute Build-Output (zitare/apps/zitare/src/content/index-min.json), ausgeliefert als statische Datei.

{
  "generatedAt": "2026-05-08T20:48:48.795Z",
  "count": 11,
  "quotes": [
    {
      "slug": "...",
      "authorSlug": "...",
      "language": "de",
      "themeSlugs": [...],
      "regionSlugs": [...],
      ...
    }
  ]
}

Native-Konsumenten: SnapshotSync (App), DailyQuoteWidget (WidgetExtension via App-Group), SpotlightIndexer (App), Submit- View (Auto-Complete für Author/Theme).

Repo-Layout

zitare-native/
├── project.yml                  XcodeGen-Manifest (SOT)
├── PLAN.md                      Phasen-Tracking
├── CLAUDE.md                    dieses File
├── README.md
├── .swiftformat, .swiftlint.yml, .gitignore
├── Sources/
│   ├── App/                     ZitareNativeApp (@main), RootView
│   ├── Features/
│   │   ├── WebShell/            WebShellView (WKWebView-Wrapper, ζ-1)
│   │   ├── Submit/              SubmitQuoteView (ζ-3)
│   │   ├── Account/             AccountView (ζ-0 stub)
│   │   └── Settings/            SettingsView (ζ-5)
│   ├── Core/
│   │   ├── Auth/                AppConfig (ManaAppConfig-Provider)
│   │   ├── API/                 ZitareAPI (Quote-DTOs, Submit, Share)
│   │   ├── Snapshot/            SnapshotSync, SnapshotStore (ζ-2)
│   │   ├── Spotlight/           SpotlightIndexer (ζ-4)
│   │   ├── Telemetry/           Log (OSLog, ev.mana.zitare)
│   │   └── Theme/               ZitareTheme (paper-Werte)
│   ├── Widgets/                 WidgetKit-Extension (ζ-2)
│   ├── ShareExtension/          „An Zitare schicken" (ζ-4)
│   └── Resources/
│       ├── Assets.xcassets      AppIcon, AccentColor
│       ├── Localizable.xcstrings
│       ├── Info.plist           (XcodeGen-generiert, gitignored)
│       └── ZitareNative.entitlements  (generiert, gitignored)
├── Tests/
│   ├── UnitTests/
│   └── UITests/
└── docs/

Wichtige Cross-Repo-Doks

• ../mana/docs/playbooks/ZITARE_NATIVE_GREENFIELD.md — vollständiger Phasen-Plan und Architektur-Begründungen
• ../mana/docs/MANA_SWIFT.md — Plattform-SOT für alle nativen Apps
• ../mana/docs/MANA_AUTH_FEDERATION.md — Auth-Protokoll, Cookie-SSO
• ../mana/docs/COMPLIANCE.md — Telemetrie/Auth/Bezahl-Regeln plus Plattform-Lock-In-Diskurs (gilt auch native)
• ../zitare/CLAUDE.md — Web-App-Konventionen
• ../zitare/STATUS.md — Web-Phasenstand (Funktions-Referenz)
• ../zitare/app-manifest.json — Föderations-Vertrag (Shares / Accepts / Link-Patterns)
• ../mana-swift-core/CLAUDE.md — ManaCore + ManaTokens
• ../mana-swift-ui/CLAUDE.md — ManaAuthUI + ManaAuthGate

Lokal entwickeln

Pre-Requisites:

• Xcode 16+
• brew install xcodegen swiftformat swiftlint
• ../mana-swift-core/ und ../mana-swift-ui/ als Schwester- Verzeichnisse (Package-Dependency via path:)

Workflow:

xcodegen generate
open ZitareNative.xcodeproj

Vor jedem Commit:

swiftformat Sources Widgets ShareExtension Tests
swiftlint --strict

Phasen-Disziplin

Jede Phase aus dem Lift-Plan hat ein verifizierbares Erfolgskriterium. Nicht in die nächste Phase reinarbeiten, bevor die vorherige abgeschlossen ist. Vollständige Phasen-Tabelle + Erfolgs-Kriterien in docs/NATIVE_LIFT_PLAN.md.

Übersicht:

• ζ-0..ζ-2: erledigt unter Hybrid-Annahme (Setup, WebShell, Snapshot- Stub + Widget-Code). WebShell entfällt jetzt; Widget + Snapshot- Code bleiben, werden in η-1 erweitert.
• η-0: De-Hybrid (ManaWebShell raus, RootView vier native Tabs) (JETZT)
• η-1: Snapshot v2 + volles SwiftData-Schema (Cross-Repo-Blocker: zitare/apps/zitare/ muss index-full.json + 7 Stammdaten-JSONs liefern)
• η-2: Read-Core nativ (Heute, Quote-Detail, Author-Detail)
• η-3: Read-Browse (Source / Theme / Place / Role / Epoch / Language)
• η-4: Explore + Filter
• η-5: Search (lokal-first + Server-Fallback)
• η-6: Account voll nativ
• η-7: Legal-Sheets via SafariView
• η-8: Submit / ShareExt / Spotlight an Snapshot v2 anpassen
• η-9: Polish (iPad-Split, Accessibility, macOS-Layout)
• η-10: TestFlight

Bei Phasen-Wechsel: PLAN.md aktualisieren + Memory-Eintrag project_zitare_native_dehybrid.md nachziehen.

Don't do

• Kein WKWebView im App-Binary. SafariView (SFSafariViewController) ist die einzige zugelassene Browser-Brücke, und nur für statisches Verein-Recht (Impressum, Datenschutz, Lizenz). Wenn du WKWebView brauchen würdest, baust du es als native View nach.
• Kein eigener FSRS-Port, kein eigener Pagefind-Klon. Existiert beides nicht für Zitare. Lokale FTS in η-5 ist SwiftData-Predicate.
• Keine Push-Notification-Pipeline. Widget reicht.
• Keine externen UI-Libs / kein Sentry / kein Crash-Reporting- SaaS. OSLog only (Compliance).
• Kein Edit / Moderation / Admin in der App. Web-Surface (app.zitare.com) bleibt SOT für schreibende Pfade jenseits von Submit. Wer das braucht, öffnet Safari.