GPS Standort Manager - Dokumentation

Übersicht

Der GPS Standort Manager ist eine containerisierte Webanwendung zur Verwaltung von GPS-Standorten mit integrierter Google Maps-Anbindung. Die Anwendung ermöglicht das Speichern, Suchen, Filtern und Visualisieren von geografischen Standorten in einer interaktiven Karte sowie die Generierung von Google Maps Links.

---

Features

• Interaktive Google Maps Karte mit allen gespeicherten Standorten als Marker
• Klick auf Karte setzt temporären Pin und überträgt Koordinaten ins Formular
• Umfangreiche Standortverwaltung: Name, Adresse, Ansprechpartner, Notizen, Tags, Favoriten
• Echtzeit-Suche über Name, Adresse, Ansprechpartner und Tags
• Filter nach Tags und Favoriten-Funktion
• Google Maps Link-Generierung für jeden Standort und manuelle Koordinaten
• Responsives Design mit Tailwind CSS – nutzbar auf Desktop und Mobilgeräten
• REST API mit automatischer API-Dokumentation (Swagger UI)
• Persistente PostgreSQL-Datenbank in Docker

---

Architektur

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   Browser   │──────│  FastAPI    │──────│  PostgreSQL │
│  (Frontend) │      │  (Backend)  │      │  (Docker)   │
└─────────────┘      └─────────────┘      └─────────────┘
       │
       └─────────── Google Maps JavaScript API

Tech-Stack

Komponente	Technologie
Frontend	HTML5, Vanilla JavaScript, Tailwind CSS, Lucide Icons
Backend	Python 3.11, FastAPI, SQLAlchemy, Pydantic
Datenbank	PostgreSQL 15
Container	Docker & Docker Compose
Karte	Google Maps JavaScript API

---

Projektstruktur

google_maps_best/
├── docker-compose.yml          # Docker Compose Konfiguration
├── .env                        # Umgebungsvariablen (API Key, DB Credentials)
├── .env.example                # Template für .env
├── backend/
│   ├── Dockerfile              # Python Container Definition
│   ├── requirements.txt        # Python Abhängigkeiten
│   ├── main.py                 # FastAPI App, Static Files, API Router
│   ├── database.py             # SQLAlchemy Engine, Session, Base
│   ├── models.py               # ORM Datenbankmodell (PostgreSQL)
│   ├── schemas.py              # Pydantic Validierungsmodelle
│   └── routers/
│       ├── __init__.py
│       └── locations.py        # REST API Endpunkte für Standorte
└── frontend/static/
    ├── index.html              # Hauptseite mit UI
    ├── css/
    │   └── style.css           # Custom Styles & Scrollbar
    └── js/
        ├── api.js              # Backend Kommunikation (Fetch API)
        ├── map.js              # Google Maps Initialisierung & Steuerung
        └── app.js              # Haupt-Applikationslogik & UI Events

---

Installation & Setup

Voraussetzungen

• Docker installiert
• Docker Compose installiert
• Google Maps API Key von der Google Cloud Console

1. Google Maps API Key beschaffen

1. Google Cloud Console öffnen
2. Ein neues Projekt erstellen oder bestehendes wählen
3. APIs & Services > Credentials aufrufen
4. Create Credentials > API Key klicken
5. Für die Maps JavaScript API aktivieren
6. Optional: IP-Beschränkungen für Sicherheit einrichten

2. Umgebungsvariablen konfigurieren

Die .env Datei im Projektordner anpassen:

# .env
GOOGLE_MAPS_API_KEY=DEIN_ECHTER_API_KEY_HIER
DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=gpsdb

Hinweis: Die .env Datei ist bereits im .gitignore eingetragen und wird nicht versioniert.

3. Anwendung starten

# Im Projektverzeichnis:
docker compose up --build -d

Dies baut das Docker Image und startet zwei Container:

• gps_postgres - PostgreSQL Datenbank auf Port 5432
• gps_api - FastAPI Backend & Frontend auf Port 8000

4. Zugriff

• Webanwendung: http://localhost:8000
• API Dokumentation (Swagger UI): http://localhost:8000/docs
• Alternative API Doku (ReDoc): http://localhost:8000/redoc

5. Anwendung stoppen

# Container stoppen & entfernen:
docker compose down

# Mit Löschung aller Daten (inkl. Datenbank):
docker compose down -v

---

Verwendung

Standort erstellen

1. Auf die Karte klicken → blauer Pin erscheint, Overlay zeigt Koordinaten
2. "Für Formular übernehmen" klicken oder Koordinaten manuell eingeben
3. Name, Adresse, Ansprechpartner, Notizen ausfüllen
4. Tags hinzufügen: Im Tag-Feld tippen und Enter drücken
5. Optional: Favorit markieren
6. "Speichern" klicken → Standort erscheint auf Karte und in der Liste

Standort bearbeiten

• Auf einen Eintrag in der Liste klicken oder "Bearbeiten" im Marker-Popup wählen
• Daten im Formular ändern
• Erneut "Speichern" klicken

Standort löschen

• Auf den Mülleimer-Icon in der Liste klicken
• Bestätigung mit "OK"

Standort auf Karte anzeigen

• Auf den Map-Pin-Icon in der Liste klicken → Karte zentriert auf den Standort

Google Maps öffnen

• Auf den External-Link-Icon in der Liste klicken
• Oder im Marker-Popup auf "Google Maps ↗" klicken
• Oder im Bearbeitungsmodus auf den Link-Button klicken

Suche & Filter

• Suchleiste: Echtzeit-Suche über Name, Adresse, Ansprechpartner, Tags
• Favoriten-Filter: Button "Favoriten" klickt, um nur Favoriten anzuzeigen

---

API Endpunkte

Methode	Endpunkt	Beschreibung
GET	/api/locations	Alle Standorte abrufen (optional mit search, tag, favorite Parametern)
POST	/api/locations	Neuen Standort erstellen
GET	/api/locations/{id}	Einzelnen Standort abrufen
PUT	/api/locations/{id}	Standort bearbeiten
DELETE	/api/locations/{id}	Standort löschen
PATCH	/api/locations/{id}/favorite	Favoriten-Status toggeln
GET	/api/config	API Key Konfiguration für Frontend

Beispiel: Standort erstellen

curl -X POST http://localhost:8000/api/locations/ \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hauptbüro",
    "latitude": 52.5200,
    "longitude": 13.4050,
    "address_street": "Unter den Linden 1",
    "address_zip": "10117",
    "address_city": "Berlin",
    "contact_person": "Max Mustermann",
    "notes": "Hauptsitz",
    "tags": ["Kunde", "Premium"],
    "is_favorite": true
  }'

Beispiel: Standorte suchen

# Nach Name suchen
curl "http://localhost:8000/api/locations?search=Berlin"

# Nach Tag filtern
curl "http://localhost:8000/api/locations?tag=Premium"

# Nur Favoriten
curl "http://localhost:8000/api/locations?favorite=true"

---

Datenbank Schema

Tabelle: locations

Feld	Typ	Beschreibung
id	SERIAL PRIMARY KEY	Eindeutige ID
name	VARCHAR(255) NOT NULL	Standortname
latitude	NUMERIC(10,8) NOT NULL	GPS Breite (-90 bis 90)
longitude	NUMERIC(11,8) NOT NULL	GPS Länge (-180 bis 180)
address_street	VARCHAR(255)	Straße
address_zip	VARCHAR(20)	Postleitzahl
address_city	VARCHAR(100)	Ort
contact_person	VARCHAR(255)	Ansprechpartner
notes	TEXT	Notizen
tags	ARRAY VARCHAR(50)	Selbst erstellbare Tags/Flags
is_favorite	BOOLEAN DEFAULT FALSE	Favoriten-Markierung
created_at	TIMESTAMP	Erstellungszeitpunkt

---

Docker Compose Konfiguration

Services

db (PostgreSQL)

• Image: postgres:15-alpine
• Port: 5432 (Host → Container)
• Volume: postgres_data (persistenter Speicher)
• Healthcheck: Prüft ob PostgreSQL bereit ist

api (FastAPI)

• Build: Aus backend/Dockerfile
• Port: 8000 (Host → Container)
• Depends_on: Wartet auf healthy db Container
• Volume: Mountet frontend/ als Read-Only für statische Dateien

Umgebungsvariablen

Variable	Standard	Beschreibung
GOOGLE_MAPS_API_KEY	-	Google Maps JavaScript API Key
DB_USER	postgres	PostgreSQL Benutzername
DB_PASSWORD	postgres	PostgreSQL Passwort
DB_NAME	gpsdb	PostgreSQL Datenbankname
DATABASE_URL	auto	Wird automatisch aus DB_* Variablen gebaut

---

Frontend Details

Layout

• Desktop: Split-View (Karte links 60%, Sidebar rechts 40%)
• Mobil: Karte oben (50vh), Sidebar unten (50vh, ausklappbar)

Interaktive Karte

• Marker für alle gespeicherten Standorte
• Blauer temporärer Pin bei Klick auf Karte
• Info-Popup bei Klick auf Marker mit Details & Aktionen
• Automatisches Zoomen auf alle Standorte (bounds fitting)

Formular

• Koordinaten-Eingabe (Lat/Lng) mit Karten-Übernahme
• Adressfelder (Straße, PLZ, Ort)
• Ansprechpartner & Notizen
• Tags: Dynamische Chip-Eingabe mit Enter
• Favoriten-Checkbox
• Google Maps Link Button (nur im Bearbeiten-Modus)

---

Troubleshooting

Karte wird nicht angezeigt

Symptom: Graue Fläche oder Fehlermeldung "Google Maps API Key fehlt"

Lösung:

1. .env Datei prüfen: GOOGLE_MAPS_API_KEY muss ein gültiger Key sein
2. Container neustarten: docker compose down && docker compose up -d
3. Google Cloud Console prüfen: Maps JavaScript API muss aktiviert sein

Datenbank-Verbindungsfehler

Symptom: API Container startet nicht oder zeigt DB-Fehler

Lösung:

1. Container-Status prüfen: docker compose ps
2. Logs ansehen: docker compose logs db
3. Healthcheck abwarten: Der api Container wartet automatisch auf die DB
4. Hart reset: docker compose down -v && docker compose up --build -d

Frontend-Änderungen werden nicht angezeigt

Symptom: Nach Änderung an HTML/JS/CSS wird alte Version angezeigt

Lösung:

• Browser-Cache leeren (Ctrl+F5 / Cmd+Shift+R)
• Container neustarten: docker compose restart api

Container lassen sich nicht starten

Symptom: Port bereits belegt

Lösung:

• Prüfen ob Port 8000 oder 5432 bereits verwendet: lsof -i :8000
• Andere Anwendung stoppen oder Ports in docker-compose.yml ändern

---

Entwicklung & Erweiterung

MSSQL statt PostgreSQL (zukünftig)

Um später auf Microsoft SQL Server umzustellen:

1. In docker-compose.yml den db Service austauschen:

db:
  image: mcr.microsoft.com/mssql/server:2022-latest
  environment:
    SA_PASSWORD: "DeinStarkesPasswort!"
    ACCEPT_EULA: "Y"

2. In backend/requirements.txt psycopg2-binary durch pyodbc ersetzen

3. In backend/database.py den Connection String anpassen:

DATABASE_URL = "mssql+pyodbc://user:pass@host/db?driver=ODBC+Driver+17+for+SQL+Server"

Neue Felder hinzufügen

1. backend/models.py - SQLAlchemy Spalte ergänzen
2. backend/schemas.py - Pydantic Feld ergänzen
3. frontend/static/index.html - Input Feld hinzufügen
4. frontend/static/js/app.js - Formular-Handling erweitern
5. Container neustarten: docker compose restart api

---

Sicherheitshinweise

• .env Datei niemals in Git einchecken (ist bereits in .gitignore)
• Google Maps API Key auf erlaubte Domains/IPs beschränken
• Für Produktiveinsatz zusätzliche Authentifizierung implementieren
• PostgreSQL Passwort ändern (nicht postgres verwenden)

---

Lizenz & Autor

Dieses Projekt wurde als internes Tool für lokale Netzwerkumgebungen entwickelt.

---

Changelog

v1.0.0 (2026-05-20)

• Initiale Version
• PostgreSQL + FastAPI + Docker Compose Setup
• Google Maps Integration mit interaktiver Karte
• CRUD für Standorte mit Tags, Favoriten, Adressen
• Responsive Tailwind CSS UI