⚠️ 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) │
│ │
│ 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
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 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/
├── 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).