Read-only PRD for a coding agent
Persönlicher 3D-Reise-Tracker als Einzelanwendung im Browser am Computer, lokal…
1. Problem, goal & success metric
Persönlicher 3D-Reise-Tracker als Einzelanwendung im Browser am Computer, lokal gespeichert ohne Konto oder Cloud. Interaktive 3D-Erdkugel mit allen 204 anklickbaren, farblich unterscheidbaren Ländern. Pro Land ein Spot mit Fakten (Hauptstadt, Einwohnerzahl, historische/kulturelle Fakten), eigenen Notizen, Sterne-Bewertung (1–5) und einem oder mehreren Reisedaten. Suchleiste, Liste gespeicherter Orte und Fortschrittsbalken (bereiste Länder von 204). Erfolg: alle 204 Länder sichtbar und anklickbar, Kachel öffnet sich pro Land, Fortschrittsbalken korrekt, Daten bleiben nach Schließen erhalten, keine Anmeldung.
2. Users & roles
Einzelner Nutzer (privater Reisender), kein Konto, keine Rollen, nur Computer/Desktop.
3. Core workflows
- App öffnen: 3D-Erdkugel wird geladen, alle 204 Länder farblich sichtbar, Ozeane hellblau (#BFE3F8), Fortschrittsbalken oben zeigt bereiste Länder von 204.
- Kugel drehen/zoomen/neigen mit Maus.
- Auf ein Land, eine Stadt, ein Dorf, einen Fluss oder einen See klicken: Kachel öffnet sich mit Fakten, Notizen, Sterne-Bewertung und Reisedaten.
- Daten eintragen/ändern und speichern: Land wird als bereist markiert, sobald mindestens ein Spot, Ort oder das Land selbst angelegt ist (auch ohne Reisedatum). Reisedatum als von-bis-Bereich (Start und Ende, optional, mehrere Bereiche möglich).
- Suchleiste nutzen, um ein Land, eine Stadt, einen Ort, einen Fluss oder einen See zu suchen und direkt die Kachel zu öffnen.
- Button „Liste gespeicherter Orte“ direkt unter der Suchleiste: durchsuchbare Liste aller gespeicherten Orte/Spots mit Land, Klick öffnet Kachel.
- App schließen und wieder öffnen: alle Daten sind noch da (LocalStorage).
- Auf der Kugel: Umschaltbar zwischen Modus „Stecknadeln“ und Modus „gefärbte Fläche“ (nur einer aktiv). Separate Ein-/Ausblend-Schalter für Länder, Orte und Spots.
4. Features & requirements
- 3D-Erdkugel (Three-Globe): alle 204 Länder sichtbar, farblich unterscheidbar, mit Maus drehen, zoomen, neigen; jedes Land anklickbar. Zusätzlich werden Städte, Dörfer, Flüsse und Seen als eigene klickbare Layer auf der Kugel angezeigt (kleine farbige Punkte für Städte/Dörfer, hellblaue Linien/Flächen für Flüsse/Seen #BFE3F8). Länderflächen werden niemals von Wasser überlagert und niemals hellblau gefärbt. Länder ohne GeoJSON-Daten werden nicht gefärbt und bleiben ohne Markierung.
- Spot-Kachel pro Land/Ort/Stadt/Dorf/Fluss/See: Fakten (Hauptstadt, Einwohnerzahl, historische/kulturelle Fakten) stammen nur aus der GeoJSON oder sind Nutzer-Notizen. Fehlende Felder werden mit "--" angezeigt, nie erfunden. Eigene Notizen (freier Text), Sterne-Bewertung (1–5), Reisedaten als von-bis-Bereich (Startdatum und Enddatum, optional, mehrere Bereiche möglich, „Termin hinzufügen“-Button), Speichern.
- Bereist-Status: Ein Land gilt als bereist, sobald mindestens ein Spot, Ort, Stadt, Dorf, Fluss, See oder das Land selbst angelegt ist (auch ohne Reisedatum). Mehrere Spots pro Land erlaubt, das Land zählt im Fortschritt nur einmal. Städte, Dörfer, Flüsse und Seen zählen nicht im Fortschritt.
- Suchleiste: Suche nach Ländernamen (aus GeoJSON), Stadtnamen, Ortsnamen, Flüssen und Seen. Treffer öffnet die Kachel.
- Liste gespeicherter Orte (Button direkt unter der Suchleiste): alle Länder/Orte/Städte/Dörfer/Flüsse/Seen mit eingetragenen Daten oder Notizen, durchsuchbar, Klick öffnet die Kachel.
- Fortschrittsbalken oben: Anteil bereister Länder von 204 als Balken und Zahl.
- Lokaler Datenspeicher: alle Daten im Browser-LocalStorage, laden beim Start, speichern bei Änderung, kein Konto, keine Cloud, keine Synchronisation zwischen Geräten.
- Kugel-Markierung: zwei Modi – (a) Stecknadeln in verschiedenen Farben an gespeicherten Orten/Spots, (b) gefärbte Länderfläche für besuchte Länder; nur ein Modus gleichzeitig aktiv, Umschalten schaltet den anderen aus.
- Sichtbarkeitsschalter: einzeln ein-/ausblendbar für Länder, Orte, Städte, Dörfer, Flüsse und Seen auf der Kugel.
5. Scope: must / later / never
- 8 must-haves is a lot for v1: move some to Later?
Never
- Social Sharing oder andere Nutzer einladen.
- Echtzeit-Synchronisation zwischen Geräten.
- Bezahlfunktionen oder Abos.
- Offline-Kartenmaterial zum Herunterladen (außer initiale Kartendaten).
- Mobile-App oder Tablet-Optimierung.
Later
- Export/Import von Daten als JSON-Datei für den manuellen Gerätewechsel.
Must
- 3D-Erdkugel mit 204 anklickbaren Ländern.
- Städte, Dörfer, Flüsse, Seen als klickbare Layer auf der Kugel.
- Spot-Kachel mit Fakten, Notizen, Sterne 1–5, von-bis-Reisedaten.
- Bereist-Status und Fortschrittsbalken (bereiste Länder von 204, zählt nur Länder, keine Städte/Dörfer/Flüsse/Seen).
- Suchleiste für Länder, Städte, Orte, Flüsse und Seen.
- Liste gespeicherter Orte, durchsuchbar.
- Lokaler LocalStorage ohne Konto oder Cloud.
- Umschaltbare Markierungsmodi und Sichtbarkeitsschalter. Hellblaue Färbung für Länderflächen ist verboten. Ozeane hellblau (#BFE3F8).
6. Screens & UI
- Hauptbildschirm: 3D-Erdkugel füllt den Bildschirm, Ozeane in hellblau (#BFE3F8), Länder in verschiedenen Farben (nie hellblau), Städte und Dörfer als kleine farbige Punkte, Flüsse und Seen als hellblaue Linien/Flächen (#BFE3F8), ohne Länderflächen zu überlagern. Oben mittig Fortschrittsbalken (Anteil bereist von 204), oben links Suchleiste, direkt darunter Button „Liste gespeicherter Orte“. Linksseitig Panel mit Markierungsmodus (Stecknadeln / Fläche) und Sichtbarkeitsschaltern für Länder, Orte, Städte, Dörfer, Flüsse, Seen. Klick auf Land/Ort/Stadt/Dorf/Fluss/See öffnet Spot-Kachel (Modal oder Panel rechts).
- Spot-Kachel: Titel (Land/Ort/Stadt/Dorf/Fluss/See), Fakten (Hauptstadt, Einwohnerzahl, Fakten – nur bei Ländern sinnvoll, sonst "--"), Textfeld Notizen, Sterne-Auswahl 1–5, Reisedaten-Liste mit von-bis-Datumseingabe (Start + Ende, optional, mehrere Bereiche möglich, „Termin hinzufügen“-Button), Speichern-Button, Schließen.
- Liste gespeicherter Orte: durchsuchbare Liste aller gespeicherten Länder/Orte/Städte/Dörfer/Flüsse/Seen mit Land, Klick öffnet Kachel.
7. Design system & visual style
- Hintergrund: #FFFFFF
- Oberfläche / Karten: #F5F7FA
- Primär-Akzent: #1A3C6E (dunkelblau)
- Sekundär-Akzent: #2E5C8A
- Text primär: #111827
- Text sekundär: #6B7280
- Ozean-Farbe: hellblau (#BFE3F8)
- Länderfarben: nie hellblau, farblich unterscheidbar
- Stadt-/Dorf-Markierungen: kleine farbige Punkte, klickbar
- Flüsse/Seen: hellblaue Linien/Flächen (#BFE3F8), überlagern keine Länderflächen
- Schrift: Inter, sans-serif
- Corner radius: 12px auf Karten und Modals
- Spacing: 8px / 16px / 24px Raster
- Licht/Dunkel: Nur Hellmodus
- Look & feel: Ruhevolle, moderne Karte im Google-Earth-Stil, großzügige weiße Flächen, subtile Schatten, klare Hierarchie
- Regel für fehlende Daten: Fehlende Hauptstadt, Einwohnerzahl oder Fakten werden als "--" angezeigt, nie erfunden. Länder ohne GeoJSON-Daten werden auf der Kugel nicht gefärbt.
8. Data model
Tabelle: spot (ein Eintrag pro Land/Ort/Stadt/Dorf/Fluss/See)
| Feld | Typ | Erforderlich | ||||
|---|---|---|---|---|---|---|
| id | String (UUID) | Ja | ||||
| country_id | String (ISO-3 oder Land-Name) | Ja | ||||
| country_name | String | Ja | ||||
| location_name | String (Ort/Name des Spots) | Nein | ||||
| type | String ('country' | 'city' | 'village' | 'river' | 'lake') | Ja |
| capital | String | Nein (wird aus GeoJSON übernommen, bei Fehlen "--") | ||||
| population | Number | Nein (bei Fehlen "--") | ||||
| facts | String (historische/kulturelle Fakten) | Nein (bei Fehlen "--") | ||||
| notes | String (eigene Notizen) | Nein | ||||
| rating | Number (1–5) | Nein | ||||
| visited_from | Date-String (ISO) | Nein (Startdatum von-bis-Bereich) | ||||
| visited_to | Date-String (ISO) | Nein (Enddatum von-bis-Bereich) | ||||
| created_at | ISO-String | Ja | ||||
| updated_at | ISO-String | Ja |
Tabelle: app_settings
| Feld | Typ | Erforderlich | |
|---|---|---|---|
| visited_country_ids | Array von Strings | Ja | |
| last_opened | ISO-String | Nein | |
| map_mode | String ('pins' | 'filled') | Ja |
| show_countries | Boolean | Ja | |
| show_locations | Boolean | Ja | |
| show_spots | Boolean | Ja |
9. APIs & integrations
APIs & integrations
Not needed: keine externen APIs, keine Cloud, keine Anmeldung. Nur eine lokale GeoJSON-Datei mit den 204 Ländern als statische Ressource im Projektordner.
10. Auth, permissions & security
Auth, permissions & security
Es gibt keine Authentifizierung. Die App läuft lokal im Browser auf einem Gerät. Alle Daten werden im LocalStorage des Browsers gespeichert. Es gibt keine Benutzerkonten, keine Rollen und keine serverseitige Sicherheit.
11. Performance, privacy & accessibility
- Keeps data on one device ("LocalStorage"), but Scope: must / later / never shares it between users or devices: add a backend, or drop the sharing
Performance, privacy & accessibility
- Performance: App lädt und zeigt die Kugel in unter 3 Sekunden auf einem gewöhnlichen Computer.
- Privacy: Alle Daten bleiben im LocalStorage des Browsers, verlassen das Gerät nie, keine Synchronisation zwischen Geräten.
- Accessibility: Nur Maus-Bedienung, keine Screenreader- oder Tastaturanforderungen.
12. Edge cases & errors
- LocalStorage leer beim ersten Start: App zeigt alle 204 Länder, Städte, Dörfer, Flüsse und Seen, Fortschrittsbalken bei 0, keine Kachel.
- LocalStorage voll oder deaktiviert: Fehlermeldung beim Speichern, App bleibt nutzbar für Ansicht.
- GeoJSON-Datei fehlt oder lädt nicht: Hinweis „Karte konnte nicht geladen werden“, Kugel bleibt leer.
- Ungültiges Datum eingegeben: Speichern wird blockiert, Hinweis „Ungültiges Datum“.
- Rating außerhalb 1–5: nicht speicherbar.
- Gleiche Spot mehrfach speichern: Überschreibt den bestehenden Eintrag für Land/Ort.
- Land ohne Reisedatum: nicht als bereist zählen, nicht in Liste gespeicherter Orte auftauchen (es sei denn, es gibt Notizen).
- Städte, Dörfer, Flüsse, Seen ohne GeoJSON-Daten: werden nicht angezeigt oder ohne Markierung gelassen.
- Mehrere von-bis-Bereiche pro Spot: jeder Bereich wird separat gespeichert, overlaps erlaubt.
- Ozeane hellblau (#BFE3F8), Länderflächen niemals hellblau und niemals von Wasser überlagert.
13. Stack & constraints
- Keeps data on one device ("LocalStorage"), but Scope: must / later / never shares it between users or devices: add a backend, or drop the sharing
Stack & constraints
Einzelne Web-App, statisch gehostet, keine eigene Datenbank, keine API-Server. Alles in einer index.html mit eingebettetem CSS und JS. Three.js r158 und Three-Globe v2.30 über CDN eingebunden. GeoJSON-Datei countries.geo.json mit 204 Ländern als lokale Datei im Projektordner. LocalStorage für alle Nutzerdaten (nur auf einem Gerät, keine Synchronisation zwischen Geräten). Gehostet auf einer kostenlosen Plattform ohne Konto-Anmeldung (z. B. Netlify Drop). Keine Wartung, keine Server-Kosten. Keine Microservices, Queues, Caches, Kubernetes oder separate API-Server.
14. Existing code & do-not-change
Existing code & do-not-change
Not needed: neues Projekt, kein bestehender Code, nichts zu schützen.
15. Build order
- Projekt-Grundgerüst: HTML/CSS/JS mit Three-Globe, GeoJSON laden, 204 Länder als anklickbare, farbige 3D-Kugel anzeigen (runnable allein: Kugel öffnet sich, Länder sichtbar).
- Spot-Kachel & Speicherung: Klick auf Land öffnet Modal mit Fakten, Notizen, Sterne, Reisedaten; speichern im LocalStorage; App-Neustart behält Daten (runnable allein: Daten überleben Refresh).
- Suchleiste & Liste: Suchleiste für Länder, Button „Liste gespeicherter Orte“, durchsuchbare Liste, Klick öffnet Kachel (runnable allein: Suche und Liste funktionieren).
- Fortschritt & Markierung: Fortschrittsbalken (bereiste von 204), Umschalter Stecknadeln/gefärbte Fläche, Ein-/Ausblend-Schalter für Länder/Orte/Spots (runnable allein: Balken und Markierungen reagieren auf Eingaben).
- Polish & Acceptance: Performance unter 3 Sekunden, alle 204 Länder sichtbar, Edge-Case-Tests (leerer LocalStorage, ungültiges Datum, doppelte Spots) (runnable allein: App komplett nutzbar).
16. Acceptance criteria & tests
Acceptance criteria & tests
- Alle 204 Länder sind auf der 3D-Kugel sichtbar, farblich unterscheidbar und einzeln anklickbar.
- Klick auf ein Land öffnet eine Kachel mit Fakten (Hauptstadt, Einwohnerzahl, Fakten), Notiz-Feld, Sterne-Bewertung 1–5 und Reisedaten-Eingabe.
- Speichern mit mindestens einem Reisedatum markiert das Land als bereist und zählt es im Fortschrittsbalken (bereiste von 204).
- Suchleiste findet ein Land und öffnet dessen Kachel.
- Button „Liste gespeicherter Orte“ öffnet eine durchsuchbare Liste aller gespeicherten Orte mit Land; Klick öffnet die Kachel.
- Nach Browser-Neustart sind alle gespeicherten Daten noch vorhanden.
- Umschalten zwischen Stecknadeln und gefärbter Fläche schaltet den jeweils anderen Modus aus.
- Ein-/Ausblend-Schalter für Länder, Orte und Spots funktionieren einzeln.
- App lädt in unter 3 Sekunden.
- Ungültiges Datum blockiert das Speichern mit Hinweis.
- Keine Anmeldung, kein Konto, keine Daten verlassen das Gerät.
- Keine erfundenen Länderfakten; nur reale GeoJSON-Daten oder Nutzer-Notizen.
- Keine doppelten Ländernamen über der Landfläche.
17. Deployment, environments & secrets
Deployment, environments & secrets
Statische Web-App, gehostet auf einer kostenlosen Plattform mit freiem Tier (z. B. GitHub Pages, Netlify oder Vercel). Keine Umgebungsvariablen, keine Secrets, keine Server-Kosten.