Eine Progressive Web App zum Lernen deutscher KFZ-Kennzeichen. Finde heraus, welcher Landkreis oder welche Stadt sich hinter einem Kennzeichen verbirgt – mit Quiz-Modus, interaktiver Karte und Offline-Unterstützung.
🎯 Kindgerecht · Datenschutzfreundlich · Offline-First
Live Demo • Dokumentation • Mitwirken
[Startseite] [Suche] [Quiz] [Karte]
- 🔍 Kennzeichen-Suche – Blitzschnelle Suche nach Kürzeln (z.B. "HH", "M", "B")
- 📍 Standort-Erkennung – Zeigt automatisch das Kennzeichen deines aktuellen Standorts (optional, privatsphärefreundlich)
- 🗺️ Interaktive Karte – Visualisierung aller Landkreise mit detaillierten TopoJSON-Geodaten
- 🎯 Quiz-Modi – Lerne spielerisch mit verschiedenen Modi:
- Normal-Modus: Zufällige Kennzeichen raten
- Battle-Modus: Gegen die Uhr unter Zeitdruck
- Fehler-Modus: Wiederhole nur falsch beantwortete Fragen
- 🏆 Gamification – Sammle Badges und Achievements beim Lernen
- 📊 Fortschritts-Tracking – Statistiken über richtige/falsche Antworten
- 📱 Progressive Web App – Installierbar auf Smartphone & Desktop
- 💾 Offline-First – Vollständige Funktionalität ohne Internetverbindung
- 🌙 Dark Mode – Automatische Anpassung ans System-Theme (hell/dunkel/system)
- ♿ Accessibility – ARIA-Labels, semantisches HTML, Screen-Reader-Unterstützung
- 🚀 Performance – Code-Splitting, Resource Hints, optimierte Ladezeiten
- 🔒 Sicherheit – Content Security Policy, Security Headers, OWASP Best Practices
- 🔄 Keine Tracking – 100% datenschutzfreundlich, keine Cookies, keine Analyse-Tools
# Repository klonen
git clone https://github.com/ndrstmr/kfzlotti-explorer.git
cd kfzlotti-explorer
# Abhängigkeiten installieren
npm install
# oder
bun install
# Persönliche Konfiguration (wichtig!)
cp .env.example .env
# Bearbeite .env und füge deine persönlichen Daten ein (Impressum)
# Entwicklungsserver starten
npm run dev
# oder
bun devDie App ist dann unter http://localhost:8080 erreichbar.
Wichtig: Vor dem ersten Build musst du die .env Datei konfigurieren!
# 1. Kopiere die Beispiel-Datei
cp .env.example .env
# 2. Bearbeite .env und fülle deine persönlichen Daten ein:
VITE_LEGAL_NAME="Dein Name"
VITE_LEGAL_STREET="Deine Straße 123"
VITE_LEGAL_CITY="12345 Deine Stadt"
VITE_LEGAL_EMAIL="deine@email.de"
VITE_GITHUB_URL="https://github.com/deinusername/kfzlotti-explorer"Wichtig: Die .env Datei wird nicht ins Git committed (sie steht in .gitignore).
Jeder Entwickler muss seine eigene .env Datei erstellen.
# Entwicklungsserver starten
npm run dev / bun dev
# Produktions-Build erstellen
npm run build / bun run build
# Development-Build (für PWA-Debugging)
npm run build:dev / bun run build:dev
# Build lokal testen
npm run preview / bun run preview
# Linter ausführen
npm run lint / bun run lint
# Tests ausführen
npm test / bun test
# Tests mit UI
npm run test:ui / bun run test:ui
# Test-Coverage anzeigen
npm run test:coverage / bun run test:coverageDie fertigen Dateien liegen nach dem Build im dist/-Ordner.
Vor der Veröffentlichung musst du deine Kontaktdaten in src/config/site.ts eintragen!
Nach deutschem Recht (§ 5 TMG) benötigen öffentliche Webseiten ein Impressum. Die Vorlage enthält Platzhalter, die du ersetzen musst:
export const siteConfig = {
appName: 'KFZlotti',
legal: {
name: '[Dein vollständiger Name]', // ⚠️ ÄNDERN!
street: '[Straße und Hausnummer]', // ⚠️ ÄNDERN!
city: '[PLZ und Ort]', // ⚠️ ÄNDERN!
email: '[Deine Kontakt-E-Mail]', // ⚠️ ÄNDERN!
},
};Die App zeigt eine Warnung an, wenn du die Platzhalter nicht ersetzt hast.
- Domain/URL: Ersetze
[YOUR-DOMAIN]inpublic/sitemap.xmlundpublic/robots.txt(falls vorhanden)
src/
├── components/ # React-Komponenten
│ ├── ui/ # shadcn/ui Basis-Komponenten
│ └── ... # App-spezifische Komponenten
├── config/ # Konfigurationsdateien
├── data/ # Statische Daten und Schemas
├── hooks/ # Custom React Hooks
├── lib/ # Hilfsfunktionen
├── pages/ # Seiten-Komponenten
└── index.css # Globale Styles & Design-Tokens
public/
├── data/ # JSON-Daten (Kennzeichen, Geodaten)
├── icons/ # App-Icons für PWA
└── manifest.webmanifest
- React 18.3 – UI-Framework mit Hooks
- TypeScript 5.8 – Typsicherheit & IntelliSense
- Vite 5.4 – Blitzschneller Build-Tool & Dev-Server
- Tailwind CSS 3.4 – Utility-First CSS
- shadcn/ui – Hochwertige, zugängliche UI-Komponenten
- React Router 6 – Client-seitiges Routing
- Vite PWA – Service Worker & Manifest
- Dexie.js – IndexedDB Wrapper für lokale Datenhaltung
- Workbox – Service Worker Strategien
- Leaflet – Interaktive Karten-Visualisierung
- TopoJSON – Komprimierte Geodaten
- React Leaflet – React-Integration für Leaflet
- Vitest – Unit & Integration Tests
- ESLint – Code-Linting
- TypeScript-ESLint – TypeScript-Regeln
- Happy DOM – Leichtgewichtige DOM-Implementierung für Tests
- Bun – Schneller JavaScript-Runtime & Package Manager (optional)
- GitHub Actions – CI/CD Pipeline
- Netlify / Vercel – Deployment-Plattformen (Konfigurationen vorhanden)
Beiträge sind herzlich willkommen! Bitte lies zuerst CONTRIBUTING.md für detaillierte Richtlinien.
- Fork das Repository
- Clone deinen Fork:
git clone https://github.com/dein-username/kfzlotti-explorer.git - Erstelle einen Feature-Branch:
git checkout -b feature/mein-feature - Installiere Dependencies:
bun install(odernpm install) - Starte den Dev-Server:
bun dev - Committe deine Änderungen:
git commit -m 'feat: Füge neues Feature hinzu' - Push zum Branch:
git push origin feature/mein-feature - Öffne einen Pull Request über GitHub
- ✅ Nutze TypeScript für alle neuen Dateien (kein
any!) - ✅ Folge dem bestehenden Code-Stil (ESLint wird automatisch geprüft)
- ✅ Schreibe Tests für neue Features (
src/**/*.test.ts) - ✅ Nutze Conventional Commits (
feat:,fix:,docs:, etc.) - ✅ Teste lokal vor dem PR:
bun test && bun run build - ✅ Stelle sicher, dass die CI-Pipeline grün ist
Wir haben Templates für:
Sei freundlich, respektvoll und konstruktiv. Dieses Projekt richtet sich auch an Kinder – halte die Community positiv!
- Keine Cookies – Kein Tracking, keine Analyse
- Lokale Speicherung – Alle Daten bleiben auf deinem Gerät (IndexedDB)
- Content Security Policy – Schutz vor XSS und Code Injection
- Security Headers – X-Frame-Options, X-Content-Type-Options, etc.
- HTTPS-Only – Sichere Verbindung erforderlich
- Open Source – Vollständig transparent und überprüfbar
Sicherheitsprobleme? Bitte melde sie verantwortungsvoll per E-Mail (siehe Impressum).
- Überprüfe, dass die App über HTTPS läuft (oder
localhost) - Stelle sicher, dass Service Worker registriert ist (Browser DevTools → Application)
- Lösche Cache und versuche es erneut:
Strg+Shift+R(Windows) /Cmd+Shift+R(Mac)
- Öffne die App einmal online, damit der Service Worker die Daten cachen kann
- Prüfe in DevTools → Application → Service Workers, ob der SW aktiv ist
- Teste mit
bun run build:devstattbun run buildfür besseres Debugging
# Cache löschen und neu installieren
rm -rf node_modules bun.lockb
bun install
bun testWeitere Hilfe: GitHub Issues
Geplante Features für zukünftige Versionen:
- Kartenvisualisierung – Interaktive Deutschland-Karte mit Kreisen
- Mehrsprachigkeit – Englische Version
- Erweiterte Statistiken – Detaillierte Lern-Analytics
- Teilen-Funktion – Quiz-Ergebnisse auf Social Media teilen
- Community-Features – High-Score-Listen (optional, datenschutzfreundlich)
- Sprachausgabe – Vorlesen der Kennzeichen für Kinder
Hast du Ideen? Erstelle einen Feature Request!
Die Kennzeichen-Daten stammen aus öffentlichen Quellen:
- Geodaten: © GeoBasis-DE / BKG (dl-de/by-2-0)
- KFZ-Kennzeichen: Wikipedia (CC BY-SA 4.0)
- Kreisgeometrien: KFZ250 Datensatz des BKG
Alle Datenquellen sind im Info-Bereich der App dokumentiert.
Dieses Projekt steht unter der EUPL 1.2 (European Union Public Licence) – siehe LICENSE für Details.
Die EUPL ist eine von der EU anerkannte Open-Source-Lizenz, kompatibel mit anderen Lizenzen wie GPL und MIT.
Die verwendeten Daten unterliegen eigenen Lizenzen:
- Geodaten: dl-de/by-2-0 – Freie Nutzung mit Quellenangabe
- KFZ-Daten: CC BY-SA 4.0 – Freie Nutzung mit Namensnennung
- GeoBasis-DE / BKG für die Bereitstellung der Geodaten
- Wikipedia für die KFZ-Kennzeichen-Datenbank
- shadcn/ui für die großartigen UI-Komponenten
- Lovable als Entwicklungsplattform
- Alle Contributors 🎉
- Issues: GitHub Issues
- Diskussionen: GitHub Discussions
- E-Mail: Siehe Impressum
Erstellt mit ❤️ und Lovable • Viel Spaß beim Kennzeichen-Lernen! 🚗