nodeMap/docs/README.md

# 📘 NodeMap – Entwicklerdokumentation

Willkommen in der Entwicklerdokumentation für **NodeMap** – einer modularen Kartenanwendung zur
Visualisierung und Bearbeitung von GIS-Daten, POIs und Gerätestatus in einer interaktiven
Leaflet-Karte.

Diese Anleitung führt dich **Schritt für Schritt** durch die wichtigsten Themen für lokale
Entwicklung, Architekturverständnis und Erweiterung.

---

## 📚 Inhaltsverzeichnis

### 🔹 Einstieg & Übersicht

- [Projektüberblick](#projektüberblick)
- [Build & Deployment](build-and-deploy.md)
- [Checkliste für Deployment](checklist.md)
- [Dynamische Marker erklärt](DynamischeMarkerErklaerung.md)

### 🧭 Architektur

- [Layer-Verbindung (Geräte)](architecture/device-layer-connection.md)

### ⚙️ Konfiguration

- [Allgemeine Übersicht](config/README.md)
- [Kartenquellen-Konfiguration (public/config.json)](#kartenquellen-konfiguration-publicconfigjson)

---

## ⚙️ Kartenquellen-Konfiguration (public/config.json)

Die Datei `public/config.json` steuert, welche Kartenquelle (z.B. OSM oder lokale Tiles) für die
Leaflet-Karte verwendet wird.

**Beispiel:**

```json
{
  "//info": "tileSources: 'local' für offline, 'osm' für online",
  "tileSources": {
    "local": "http://localhost/talas5/TileMap/mapTiles/{z}/{x}/{y}.png",
    "osm": "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
  },
  "active": "osm"
}
```

- Mit `active` kann zwischen Online- und Offline-Karten umgeschaltet werden.
- Die Datei wird beim Start der App automatisch geladen.
- Für Offline-Betrieb muss das lokale Kartenmaterial vorhanden sein (siehe Installationsanleitung).

### 🧩 Hauptkomponenten

- [MapComponent](components/mainComponent/MapComponent.md)
- [useInitializeMap](components/mainComponent/hooks/useInitializeMap.md)

### 🗺️ Kontextmenü

- [Übersicht Kontextmenü](components/contextmenu/README.md)
- [useMapContextMenu Hook](components/contextmenu/useMapContextMenu.md)
- [CoordinatePopup](components/contextmenu/CoordinatePopup.md)

### ➕ POIs

- [POI hinzufügen (AddPOIModal)](components/pois/AddPOIModal.md)
- [POI bearbeiten (PoiUpdateModal)](components/pois/PoiUpdateModal.md)

### 📏 GIS-Polylinien

- [PolylineContextMenu](components/gisPolylines/PolylineContextMenu.md)
- [StartIcon](components/gisPolylines/icons/StartIcon.md)
- [EndIcon](components/gisPolylines/icons/EndIcon.md)
- [CircleIcon](components/gisPolylines/icons/CircleIcon.md)
- [SupportPointIcons](components/gisPolylines/icons/SupportPointIcons.md)

### 💡 UI-Komponenten

- [CoordinateInput](components/uiWidgets/CoordinateInput.md)
- [VersionInfoModal](components/uiWidgets/VersionInfoModal.md)
- [EditModeToggle](components/uiWidgets/mapLayersControlPanel/EditModeToggle.md)
- [MapLayersControlPanel](components/uiWidgets/mapLayersControlPanel/MapLayersControlPanel.md)

### 🧪 Weitere Tools

- [TestScript (Debug)](components/TestScript.md)

---

## Projektüberblick

NodeMap wird von **TALAS.web** über einen iFrame geladen. Die Anwendung basiert auf folgenden
Technologien:

| Technologie   | Zweck                          |
| ------------- | ------------------------------ |
| Next.js       | React-Framework (Frontend/SSR) |
| Leaflet       | Kartendarstellung              |
| Redux Toolkit | Zustandverwaltung              |
| Tailwind CSS  | Styling                        |
| MySQL         | Datenbank                      |
| Node.js / IIS | Server und Auslieferung        |

👉 Mehr zur Systemarchitektur: [architecture.md](architecture.md)

---

## Projektstruktur & Setup

### Zielsystem

- Offline-Umgebung
- Windows-Server mit IIS
- Datenzugriff über TALAS-Webservice oder lokale API

### Lokale Entwicklung

➡ [Entwicklungs-Setup](guide/setup-dev.md)  
➡ [Projektstruktur erklärt](guide/project-structure.md)  
➡ [Abhängigkeiten & Tools](guide/dependencies.md)  
➡ [Umgebungsvariablen (env-Dateien)](guide/env.md)

---

## Webservices & API-Fluss

NodeMap verwendet zwei Quellen für Daten:

1. **TALAS-WebServices** (Port 80) – POIs, Geräte, Rechte, Linien usw.
2. **Lokale Next.js API** (Port 3000) – direkte Datenbankzugriffe via MySQL

➡ [Webservices-Dokumentation](guide/webservices.md)

---

## Zustandverwaltung Redux

Die komplette Anwendung verwendet Redux zur globalen Zustandverwaltung.

- Architektur: `Service → Thunk → Slice → Komponente`
- Beispiel: POIs, Marker, Linien, Rechte, Layer-Status
- Redux DevTools werden unterstützt

➡ [Zustandverwaltung mit Redux](guide/redux-zustand.md)

---

## Entwicklung & Testdaten

Zur Entwicklung ohne echte API stehen lokale Mockdaten zur Verfügung:

- Aktivierung über `.env.development → NEXT_PUBLIC_USE_MOCKS=true`
- In `.env.production` sollte `NEXT_PUBLIC_USE_MOCKS=false` gesetzt sein
- Nutzung z. B. in `pages/api/mocks/...`
- Hinweise im UI zeigen aktivierten Mockmodus

➡ [Mockdaten & Entwicklung](guide/mock-data.md)

---

## Fehlerbehandlung & Glossar

Typische Probleme (z. B. Webservice nicht erreichbar, Layer nicht sichtbar) werden in der FAQ
gesammelt.  
Zudem gibt es eine Begriffsliste zur Orientierung:

➡ [FAQ & häufige Fehler](guide/faq.md)  
➡ [Glossar](guide/glossar.md)

---

## Hinweis zum Deployment

📦 Die Anleitung für Server-Installation und ZIP-Deployment findest du in:  
➡ [Root-README.md](../README.md)

---

## Tipp

Wenn du neu im Projekt bist, beginne mit dem Kapitel **Projektstruktur & Setup** und folge dann über
die Webservices bis zu den Komponenten.