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 ../mana/docs/playbooks/ZITARE_NATIVE_GREENFIELD.md. Dieses CLAUDE.md ist die Konventions- und Cross-Repo-Referenz.

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    │  WKWebView (Lesen)
   (statisch, public)                │ (this repo)      │  SwiftUI (Submit)
                                     │ ev.mana.zitare   │  WidgetKit
   zitare-api        ◄────────────   │                  │  SwiftData (Snapshot-Cache)
   zitare-api.mana.how               │                  │  CoreSpotlight
                                     └──────────────────┘

Status

Phase ζ-0 — Setup. Repo-Skelett, project.yml, leerer Build im Simulator. Phasen ζ-1 bis ζ-7 in ../mana/docs/playbooks/ZITARE_NATIVE_GREENFIELD.md.

Leitprinzip: Verteilungs-USP, nicht Funktions-USP

Anders als die anderen drei nativen Apps (cards/memoro/manaspur) gibt es bei Zitare keinen Hardware-Vorteil gegenüber dem Browser. Die Web-App ist mobile-responsive, statisch prerendered, hat Pagefind- client-Suche. Native bringt:

1. Home-Screen-Widget „Zitat des Tages"
2. ShareExtension als Ziel für markierten Text
3. Spotlight-Index für system-weite Suche
4. Native Submit-View mit ManaAuthUI

Alles andere (Lesen, Filtern, Search, Edit, Moderation) bleibt im WKWebView gegen zitare.com / zitare.mana.how.

Architektonische Invarianten

Beschlossen. Nicht ohne explizite Diskussion antasten.

1. Hybrid ausnahmsweise. Lese-Surfaces via WKWebView, Native- Surfaces (Widget, ShareExt, Submit, Spotlight) pure SwiftUI. Diese Trennung ist fest — keine schleichende Native-Re-Implementation von Read-Routes.
2. Read-only via Web, Submit via SwiftUI. Submit ist der einzige schreibende Pfad in v1. Edit, Moderation, History bleiben Web.
3. Snapshot lokal gespiegelt für Widget + Spotlight. Beim Launch https://zitare.com/index-min.json pullen, in SwiftData persistieren, App-Group group.ev.mana.zitare reicht es an Widget
   • ShareExtension durch. Nicht für den WebView-Pfad — der lädt live.
4. mana-auth via ManaCore + ManaAuthUI. Submit-Pfad nutzt AuthClient und die fertigen Views aus ManaAuthUI. Keine eigene Auth. WebView gegen zitare.mana.how bekommt JWT per Cookie- Injection (mana.access auf .mana.how).
5. Universal-Link-Domain: zitare.com. AASA auf https://zitare.com/.well-known/apple-app-site-association. zitare.mana.how ist kein applinks-Ziel.
6. Theme: paper-Variant default. Werte aus @mana/themes/paper, lokal als ZitareTheme.swift nachgebaut.
7. Bundle-ID ev.mana.zitare. Reverse-Domain mana-ev.ch. App-Display-Name: „Zitare". Category: public.app-category.reference.
8. Pure SwiftUI für Native-Surfaces. WKWebView ist die einzige UIKit-Bridge.
9. Web gewinnt bei Konflikt. Funktion wandert zuerst in zitare/apps/zitare/ oder zitare/apps/api/, dann ins WebView- bzw. Native-Surface hier.

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 Greenfield-Plan hat ein verifizierbares Erfolgskriterium. Nicht in die nächste Phase reinarbeiten, bevor die vorherige abgeschlossen ist:

• ζ-0: leerer Build + ManaCore-Login + Healthz-Probe (JETZT)
• ζ-1: WebShellView + Universal-Links + Cookie-SSO-Bridge
• ζ-2: Snapshot-Sync + DailyQuoteWidget auf realem Gerät
• ζ-3: Submit-View nativ mit ManaAuthGate
• ζ-4: Spotlight + ShareExtension + App Intents
• ζ-5: Polish, Theme-Sync, iPad-Split-Layout, Accessibility
• ζ-6: App-Store-Submission

Bei Phasen-Wechsel: PLAN.md aktualisieren + Memory-Eintrag project_zitare_native.md nachziehen (sobald angelegt).

Don't do

• Keine Native-Re-Implementation der Read-Routes. Wenn dir die Web-Quote-Ansicht im WebView nicht gefällt, fixe sie in ../zitare/apps/zitare/src/routes/(read)/. Nicht hier eine zweite bauen.
• Kein eigener FSRS-Port, kein eigener Pagefind-Klon. Existiert beides nicht für Zitare und soll nicht entstehen.
• Keine Push-Notification-Pipeline. Widget reicht.
• Keine externen UI-Libs / kein Sentry / kein Crash-Reporting- SaaS. OSLog only (Compliance).
• Keine offline-Volltext-Funktion im WebView. Wenn Offline- Lesen Use-Case wird → PWA-Pfad (Option A in zitare/CLAUDE.md), nicht hier.