⚠️ Hinweis: Dieses Projekt wurde größtenteils KI-generiert (mit GitHub Copilot). Nicht der gesamte Code wurde bisher manuell reviewed – Vorsicht bei produktivem Einsatz, Beiträge und Reviews sind willkommen.

tiptoi-sync

Android-App zum Suchen, Herunterladen und Synchronisieren von tiptoi-Büchern auf den tiptoi-Stift. Läuft direkt auf dem Smartphone (Capacitor-App) – kein Server, kein selbst-gehostetes Backend nötig.

---

Features

• Barcode-Scanner – Buch per Kamera-Scan (QR/EAN) suchen
• Freitextsuche – nach Titel oder Artikelnummer suchen
• Download – GME-Datei + Cover automatisch von Ravensburger herunterladen
• Bibliothek – alle heruntergeladenen Bücher in der Übersicht
• Stift-Sync – tiptoi-Stift verbinden (Storage Access Framework), Bücher direkt aus der App auf den Stift kopieren
• Stift-Status – zeigt welche Bücher bereits auf dem Stift sind und welche fehlen

---

Architektur

Die App läuft komplett nativ auf dem Android-Gerät – Suche, Download und Stift-Zugriff passieren alle direkt im Client, ohne Server-Komponente:

┌───────────────────────────────────────────────┐
│  Android-App (Capacitor + SolidJS)             │
│                                                 │
│  client/src/api.ts   → Ravensburger-Suche +    │
│                        Download-Orchestrierung │
│                                                 │
│  Native Plugin (Kotlin, TiptoiPlugin.kt):      │
│   - Download von GME-Datei + Cover             │
│   - Stift-Zugriff via SAF (Storage Access       │
│     Framework, Verzeichnis-Picker)             │
│   - Auflisten/Kopieren/Löschen von .gme auf     │
│     dem Stift                                  │
└───────────────────────────────────────────────┘

Details zu Modulaufteilung und Konventionen: siehe .github/copilot-instructions.md.

---

Voraussetzungen

• Bun ≥ 1.0
• Android SDK + Gradle (für lokale Android-Builds) oder Docker/Podman (für den containerisierten APK-Build, siehe unten)
• Android-Gerät oder -Emulator zum Testen

---

Entwicklung (lokal)

git clone <repo>
cd tiptoi-sync
bun install

# Vite Dev Server starten (Web-Ansicht im Browser)
bun run dev

• Web-Ansicht: http://localhost:5173 (Vite Dev Server mit HMR)

Für Live-Reload direkt auf dem Android-Gerät/-Emulator gegen den Vite Dev-Server:

bun run cap:sync
DEV_URL=http://<host-ip>:5173 bun run cap:android

client/capacitor.config.ts liest DEV_URL und lädt die Webview dann direkt vom Dev-Server statt vom gebauten dist/-Ordner. Alternativ lässt sich das auch zur Laufzeit über das Dev-Menü in der App umschalten (5x auf den Titel in der Kopfzeile tippen).

---

Android-APK bauen

Über Docker/Podman (empfohlen, kein lokales Android SDK nötig)

./build-apk.sh

Baut die APK reproduzierbar in einem Container (Bun + Android SDK + Gradle, siehe Dockerfile.android) und legt sie unter apk-output/tiptoi-sync.apk ab.

Lokal mit installiertem Android SDK

bun run build           # Web-Assets bauen
bun run cap:sync        # Assets ins Android-Projekt synchronisieren
cd client/android
./gradlew assembleDebug

---

CI

Ein Workflow unter .github/workflows/ci.yml führt bei jedem Push/PR auf main einen Type-Check aus und baut anschließend die APK, die als Artifact bereitgestellt wird. Kompatibel sowohl mit GitHub Actions als auch mit Gitea Actions.

---

Projektstruktur

tiptoi-sync/
├── client/                       # SolidJS + Capacitor App
│   ├── src/
│   │   ├── api.ts                # Ravensburger-Suche, Download-/Sync-Orchestrierung
│   │   ├── native/               # TS-Interfaces für native Capacitor-Plugins
│   │   ├── pages/
│   │   │   ├── ScanPage.tsx       # Barcode-Scanner + Suche
│   │   │   └── DownloadsPage.tsx  # Bibliothek + Stift-Sync
│   │   └── components/
│   └── android/                  # Capacitor Android-Projekt (im Repo eingecheckt)
│       └── app/src/main/java/com/tiptoisync/app/
│           ├── TiptoiPlugin.kt    # Stift-Zugriff (SAF), Download, Bibliothek
│           └── DevPlugin.kt       # Live-Reload gegen Vite Dev-Server
├── Dockerfile.android            # Container-Build für die APK
├── build-apk.sh                  # Wrapper um Dockerfile.android (Podman/Docker)
└── .github/
    ├── workflows/ci.yml          # Type-Check + APK-Build
    └── copilot-instructions.md   # Architektur- und Konventions-Details

---

Hinweise

• Kein direkter USB-Massenspeicher-Zugriff nötig – der Stift wird über das Android Storage Access Framework (SAF) via Verzeichnis-Picker eingebunden, kein Root/Server erforderlich.
• Die App ist bewusst Android-only: ein Web-/iOS-Backend existiert nicht (mehr).