# Architektur

## Leitlinien

- Offline und ohne nachzuinstallierende Laufzeit nutzbar
- reproduzierbare Windows-x64-Pakete mit `jpackage`
- reaktionsfähige Oberfläche; große Dateien werden nie im UI-Thread verarbeitet
- gemeinsam nutzbare Kernmodelle für eine spätere MapTools-Windows-App
- austauschbare Import-, Filter- und Exportkomponenten
- vollständig portable Laufzeitablage ohne AppData-, XDG- oder System-Temp-Schreibzugriffe

## Module

### `core`

Kotlin-Multiplatform-Modul mit plattformunabhängigen Dateiformaten, Gebiets- und Auftragsmodellen. Plattformspezifische Adapter liegen in eigenen Source-Sets; `desktopMain` enthält derzeit den dateibasierten PBF-Headerleser.

Der PBF-Headerleser wertet ausschließlich den ersten `OSMHeader`-Blob aus. Er unterstützt RAW- und ZLIB-Daten, begrenzt Blob-Header auf 64 KiB sowie entpackte Headerdaten auf 32 MiB und lädt keine OSM-Kartenelemente. Die ermittelten Grenzen werden auf die normalisierte Rechteckauswahl abgebildet.

Mehrere Quellen behalten eigene Header-, Vorschau- und Konvertierungscaches. Für die Bedienoberfläche
werden ihre geografischen Grenzen vereinigt und die Vorschaugeometrien kollisionsarm zusammengeführt.
Mapsforge-`.poi`-Dateien werden als unabhängige, kombinierbare Quellen geführt und können allein oder mit
Kartenquellen verwendet werden. Metadaten, Bounds, Schema und POI-Anzahl werden schreibgeschützt aus SQLite
gelesen. Für den Export werden alle POI-Quellen räumlich gefiltert, auf ein gemeinsames Schema normalisiert
und danach mit neu zugeordneten POI- und Kategorie-IDs vereinigt.

Der Blockscanner liest die Quelldatei sequenziell, hält höchstens einen auf 32 MiB begrenzten Blob im Speicher und erfasst Offsets, Größen, Typ und Kompression. Gleichzeitig entsteht ein SHA-256-Fingerabdruck. Der binäre `.mtcidx`-Index besitzt eine Formatversion, wird über eine temporäre Datei atomar ersetzt und kann wahlweise per vollständigem SHA-256 gegen die Quelle validiert werden.

### `desktopApp`

Compose-Multiplatform-Desktop-Oberfläche. Enthält Windows-Dateiauswahl, Kartenansicht, Fortschritt, Protokolle und die Prozesssteuerung der Worker.
Die Kartenansicht normalisiert die Geometriegrenzen einmalig und ordnet Linien, Flächen, POIs und
Beschriftungen einem 96 × 96-Raster zu. Viewport-Abfragen überspringen dadurch nicht sichtbare Daten,
während große, mehrere Rasterzellen überspannende Geometrien über eine separate globale Liste erhalten
bleiben. Die geografische Bounding-Box wird bidirektional auf das normalisierte Auswahlrechteck abgebildet.

Ab einem Zoomfaktor von sieben fragt die Oberfläche den sichtbaren geografischen Bereich nach einer
kurzen Entprellzeit erneut ab. Mapsforge-Quellen liefern die Vektordaten direkt über ihren Kachelindex.
Für PBF-Quellen erzeugt ein isolierter Worker einmalig eine interne Mapsforge-v5-Karte und POI-v4-Datenbank
unter `cache/preview/detail`; beide sind durch Pfad, Größe und Änderungszeit der Quelle versioniert.
Die POI-Datenbank ergänzt die sofort verfügbare Suche im begrenzten Übersichtsindex. Suchtreffer werden
auf der Karte zentriert und nur für die laufende Sitzung markiert.

Der POI-Worker migriert jede Quelle v3 ↔ v4 auf einer temporären Kopie. v3 → v4 ersetzt den normalen
Koordinatenindex durch RTree und erzeugt FTS5 aus `poi_data`; v4 → v3 erzeugt wieder `lat`/`lon` und entfernt
FTS5. Anzahl und referenzierte IDs werden vor dem Commit verglichen. Kartenformat v4 ↔ v5 verwendet dagegen
den vorhandenen Mapsforge-Leser, die interne PBF-Materialisierung und den offiziellen Writer.

Die Gebietsauswahl besteht aus gemeinsamen Formmodellen für normalisierte Rechtecke und Kreise mit einem
geografischen Radius in Kilometern. Rechteckvereinigungen werden exakt berechnet; gemischte Vereinigungen
verwenden deterministische sphärische Streifenintegration und vereinigen die Intervalle jedes Streifens,
sodass Überlappungen nicht mehrfach eingehen. Der Vorschauindex vereinigt eindeutige Objektindizes.
Der Worker prüft Nodes in einem gemeinsamen MTCI-Durchlauf gegen alle tatsächlichen Formen, nimmt
abhängige Ways und Relations nur einmal auf und schreibt als Dateigrenze die rechteckige Hülle aller
Teilgebiete. Der Worker-Codec bleibt zu älteren, unmarkierten Rechteckargumenten kompatibel.

### Worker

- `worker`: separater JVM-Prozess auf Basis von Osmosis 0.49.2 für PBF-Zuschnitt und Filterung; läuft mit der gebündelten Java-Laufzeit
- `mapsforge-writer`: wird als Osmosis-Plugin im selben Worker für `.map`- und `.poi`-Erzeugung angebunden

Worker werden getrennt ausgeführt, damit ein fehlerhafter Datensatz nicht die Benutzeroberfläche beendet und Fortschritt sowie Abbruch kontrollierbar bleiben.

Der Höhen-Worker indiziert Quellen und Auswahlformen nach geografischen Gradkacheln. Der GeoTIFF-Writer
berechnet pro Rasterzeile die tatsächlich ausgewählten Längengradintervalle, zerlegt das Raster in
begrenzte Streifen und schreibt diese parallel an feste Dateioffsets. Workerzahl und Puffergröße werden
aus CPU-Zahl, freiem physischem Speicher und Heap-Spielraum bestimmt; die Ausgabe bleibt unabhängig von
der Parallelität byteidentisch. HGT- und DTED-Quellen verwenden parallele absolute Speicherzugriffe,
während zustandsbehaftete ASC- und GeoTIFF-Leser ihre Abfragen serialisieren.

Der jpackage-Launcherpfad bestimmt den portablen Speicherstamm. `cache/preview`, `cache/conversion`
und `logs` liegen neben der ausführbaren Datei. Die UI erzeugt pro Prozess `temp/session-<PID>-<UUID>`
und übergibt ihn explizit an den Worker sowie als `java.io.tmpdir`. Damit verwenden auch Bibliotheken
keinen Benutzer-Tempordner. Die Sitzung wird beim Beenden rekursiv entfernt; verwaiste Sitzungen
beendeter Prozesse werden beim nächsten Start bereinigt.

Für jede `.map`-Ausgabe erzeugt der Worker aus den gewählten Inhaltsgruppen ein temporäres
Mapsforge-Tag-Mapping auf Basis des offiziellen 0.29.0-Mappings. Straßen, Pfade, Gebäude,
Land/Wasser und POIs werden dadurch wirklich aus der Ausgabekarte ein- oder ausgeschlossen.
Der optionale PBF-Ausschnitt bleibt dagegen als vollständiger OSM-Rohdatenausschnitt erhalten.

Bei einer räumlichen Teilmenge wird auch für einen reinen `.map/.poi`-Auftrag zuerst ein temporärer,
referenziell vollständiger PBF-Ausschnitt erzeugt. Eingaben bis 256 MiB verwendet der Mapsforge-Writer
im RAM-Modus; erst größere Eingaben greifen auf HD-Indizes zurück. Dadurch sank der gemessene
Map-Writer-Anteil des Hessen-Testausschnitts von rund 188 auf 10,8 Sekunden.

Bei einem Mehrquellenauftrag wird jede geografisch relevante PBF zunächst separat und referenziell
vollständig zugeschnitten. Mapsforge-Eingaben werden für den gewählten Ausschnitt aus ihren gespeicherten
Vektorgeometrien und Tags in einen synthetischen PBF-Zwischenstrom mit getrenntem ID-Namensraum überführt.
Osmosis sortiert die Ergebnisse nach Objekttyp und ID und vereinigt sie mit
versionsbasierter Konfliktauflösung. Erst dieses deduplizierte Ergebnis wird an die Mapsforge-Writer
weitergegeben.

Die JVM-Lösung vermeidet eine zusätzliche native Windows-Toolchain und plattformspezifische DLLs. Osmosis ist Public Domain; Mapsforge steht unter LGPL 3 mit der vom Projekt dokumentierten Erleichterung für kombinierte Anwendungen. Versions- und Lizenztexte werden im Release gebündelt.

## Formatumfang

Erster tatsächlich verarbeiteter Importumfang: `.osm.pbf`, `.pbf` und Mapsforge `.map`. Die Oberfläche erkennt weitere
OSM-Endungen bereits, deren Parser werden aber erst nach dem stabilen PBF-Workflow freigegeben.

Erster Exportumfang: Mapsforge `.map`, Mapsforge `.poi` und bei reinen PBF-Quellen zugeschnittenes
`.osm.pbf`. Aus `.map` können ursprüngliche OSM-IDs und beim ersten Kartenbau verworfene Tags nicht
rekonstruiert werden; deshalb wird die Rohdaten-Ausgabe bei mindestens einer `.map`-Quelle deaktiviert.
