# openorienteering/mapper architecture

> Architecture diagram of the GitHub repository openorienteering/mapper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openorienteering/mapper
- Repository: https://github.com/openorienteering/mapper

## Overview

##### Project type and purpose
- This is a full‐stack, cross‐platform desktop/mobile application for orienteering map creation (“OpenOrienteering Mapper”).
- It uses C++/Qt for core logic and GUI, with an Android front end in Java, plus extensive file I/O, printing, sensor‐plugin integration, and vectorization via third‐party libraries.

##### File structure
- Top‐level build/config: CMakeLists.txt, cmake/, ci/, packaging/
- Third‐party code: 3rd-party/clipper (geometry clipping), 3rd-party/cove (vectorizer), 3rd-party/qtsingleapplication
- Source directories under src/:
- src/gui – Qt GUI views, dialogs, controllers (MVC pattern)
- src/core – data model, map representation, coordinate systems, symbol logic
- src/fileformats – file import/export registry and format implementations (OCD, IOF, KML, XML)
- src/gdal – GDAL‐backed file I/O and georeferencing support
- src/printsupport – PDF/printer backends with platform patches
- src/sensors – plugin framework for GPS/compass inputs (JSON plugin descriptors)
- src/tools, src/templates, src/undo – map‐editing tools, template management, undo stack
- src/android – Java entry/activity/service that loads the native Qt engine via JNI
- Packaging: platform‐specific installers for Windows (NSIS), macOS (hdiutil), Linux (desktop files, Android packages).
- Tests: test/ directory with unit tests per module.
- Translations: Qt .ts files and scripts.

##### README for additional insights
- Confirms cross‐platform support (Android, Windows, macOS, Linux).
- Points to CMake build instructions (INSTALL.md).
- Mentions API docs, manual, translation workflow.

a. Main components
- User Interfaces
- Qt Desktop GUI (src/gui)
- Android UI (Java + native Qt via JNI)
- Core Engine
- Data model (src/core)
- Geometry & coordinate transformations
- Symbol management
- Undo/redo manager
- File I/O & Geospatial Services
- Fileformats registry (multiple formats)
- GDAL integration (src/gdal)
- Rendering Pipeline
- Qt QPainter/QGraphics-based rendering
- Tools & Plugins
- Editing tools (src/tools)
- Template management (src/templates)
- Sensor plugins (src/sensors)
- Printing Support
- Advanced PDF engine (src/printsupport)
- Packaging & CI
- Build scripts (CMake, ci/)
- Platform packages (packaging/)
- External Dependencies
- GDAL, Qt, C++ standard library

b. Relationships & interactions
- UI layers invoke Core Engine to manipulate map state.
- Core Engine delegates file load/save to File I/O & GDAL modules.
- Rendering Pipeline subscribes to model changes and draws via QPainter.
- Tools plug into Core Engine to modify map objects; Undo manager tracks operations.
- Sensor plugins feed live GPS/compass data into Core Engine.
- Printing Support reads map model and uses vectorizer to generate printable output.
- Packaging & CI orchestrate builds of all components and bundles dependencies.

c. Architectural patterns & principles
- Model-View-Controller: src/core (Model), src/gui/View + Controller classes (e.g., MainWindowController)
- Plugin registry: fileformats and sensors use a registration pattern for extensibility
- Layered architecture: clear separation of UI, business logic, data access, rendering
- Cross‐platform abstraction: platform‐specific code isolated under src/android, src/printsupport, packaging/

d. Key technologies & libraries
- Qt (Widgets, QPainter, QML not used here)
- CMake build system, Azure Pipelines / GitHub CI
- GDAL for geospatial I/O
- 3rd‐party/cove & clipper for vectorization
- JNI bridging for Android
- NSIS, hdiutil, CPack for packaging
- Weblate / Qt .ts for translations

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        DesktopGui["Qt Desktop GUI"]:::ui
        subgraph AndroidUI["Android UI"]
            MA["MapperActivity"]:::ui
            MS["MapperService"]:::ui
        end
    end

    %% Core Engine
    subgraph "Core Engine"
        CoreEngine["Core Engine\n(Map Model,\nCoord Systems,\nSymbol Mgmt)"]:::core
        UndoMgr["Undo/Redo Manager"]:::core
    end

    %% I/O & Services
    subgraph "File I/O & Geospatial Services"
        FileFormats["File I/O & Format Registry"]:::io
        GDAL["GDAL Geospatial Services"]:::io
    end

    %% Rendering Pipeline
    subgraph "Rendering Pipeline"
        Rendering["Rendering Pipeline\n(QPainter/QGraphics)"]:::io
        subgraph "Vectorization"
            Cove["Cove (vectorizer)"]:::ext
            Clipper["Clipper (geometry clipping)"]:::ext
        end
    end

    %% Plugins & Tools
    subgraph "Plugins & Tools"
        Tools["Map-Editing Tools"]:::core
        Templates["Template Management"]:::core
        Sensors["Sensor Plugins Framework"]:::core
    end

    Printing["Printing Support\n(PDF/printer backends)"]:::io
    PackagingCI["Packaging & CI"]:::pkg

    %% Relationships
    DesktopGui -->|"manipulate"| CoreEngine
    MA -->|"JNI call"| CoreEngine
    MS -->|"JNI call"| CoreEngine
    CoreEngine -->|"saveMap()/loadMap()"| FileFormats
    CoreEngine -->|"saveMap()/loadMap()"| GDAL
    FileFormats -->|"use GDAL libs"| GDAL
    CoreEngine -->|"render()"| Rendering
    Rendering -->|"vectorize() or clip()"| Cove
    Rendering -->|"vectorize() or clip()"| Clipper
    Printing -->|"generate print"| CoreEngine
    Printing -->|"vectorize() for PDF"| Cove
    Printing -->|"vectorize() for PDF"| Clipper
    Tools -->|"modify map"| CoreEngine
    Tools -->|"record action"| UndoMgr
    Templates -->|"apply template"| CoreEngine
    Sensors -->|"loadSensorData()"| CoreEngine
    PackagingCI -->|"build Qt Desktop"| DesktopGui
    PackagingCI -->|"build Android"| MA
    PackagingCI -->|"build Android"| MS
    PackagingCI -->|"build Core"| CoreEngine
    PackagingCI -->|"bundle printing"| Printing

    %% Click Events
    click DesktopGui "https://github.com/openorienteering/mapper/tree/master/src/gui"
    click MA "https://github.com/openorienteering/mapper/blob/master/src/android/java/org/openorienteering/mapper/MapperActivity.java"
    click MS "https://github.com/openorienteering/mapper/blob/master/src/android/java/org/openorienteering/mapper/MapperService.java"
    click CoreEngine "https://github.com/openorienteering/mapper/tree/master/src/core"
    click UndoMgr "https://github.com/openorienteering/mapper/tree/master/src/undo"
    click FileFormats "https://github.com/openorienteering/mapper/tree/master/src/fileformats"
    click GDAL "https://github.com/openorienteering/mapper/tree/master/src/gdal"
    click Rendering "https://github.com/openorienteering/mapper/tree/master/src/core/renderables"
    click Cove "https://github.com/openorienteering/mapper/tree/master/3rd-party/cove"
    click Clipper "https://github.com/openorienteering/mapper/tree/master/3rd-party/clipper"
    click Tools "https://github.com/openorienteering/mapper/tree/master/src/tools"
    click Templates "https://github.com/openorienteering/mapper/tree/master/src/templates"
    click Sensors "https://github.com/openorienteering/mapper/tree/master/src/sensors"
    click Printing "https://github.com/openorienteering/mapper/tree/master/src/printsupport"
    click PackagingCI "https://github.com/openorienteering/mapper/tree/master/packaging/"
    click PackagingCI "https://github.com/openorienteering/mapper/tree/master/ci/"
    click qtsingle "https://github.com/openorienteering/mapper/tree/master/3rd-party/qtsingleapplication"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#007acc
    classDef core fill:#DFFFE0,stroke:#2d882d
    classDef io fill:#FFE8C2,stroke:#e69900
    classDef ext fill:#FFF5B1,stroke:#d4af37
    classDef pkg fill:#D3D3D3,stroke:#888
```
