# maproom/qmapshack architecture

> Architecture diagram of the GitHub repository maproom/qmapshack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maproom/qmapshack
- Repository: https://github.com/maproom/qmapshack

## Overview

QMapShack is a desktop GIS for planning and analysing GPS activities. The principal workflow is to work with GPS items in a project-oriented workspace, view them on a map, and edit or analyse tracks and routes; routing, elevation, and device synchronisation extend that workflow. The tree supports the database, canvas, DEM, device, and GIS layers shown here. Several README capabilities (notably map and routing implementations) are not represented by sampled source, so those links use only documented behavior and the existing enclosing source directory.

Main entry points: [`src/qmapshack/gis/CGisWorkspace.cpp`](https://github.com/maproom/qmapshack/blob/dev/src/qmapshack/gis/CGisWorkspace.cpp) (GIS workspace), [`src/qmapshack/canvas/CCanvas.cpp`](https://github.com/maproom/qmapshack/blob/dev/src/qmapshack/canvas/CCanvas.cpp) (Map canvas), [`src/qmapshack/CMainWindow.cpp`](https://github.com/maproom/qmapshack/blob/dev/src/qmapshack/CMainWindow.cpp) (Main window), [`src/qmapshack`](https://github.com/maproom/qmapshack/tree/dev/src/qmapshack) (Tracks and routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_application["Desktop application"]
  node_entry["Application entry<br/>[main.cpp]"]
  node_window["Main window<br/>[CMainWindow.cpp]"]
end

subgraph group_gis["GIS workspace"]
  node_workspace["GIS workspace<br/>[CGisWorkspace.cpp]"]
  node_gisdb["GIS database<br/>[CGisDatabase.cpp]"]
  node_dbbackends[("Database backends")]
end

subgraph group_maps["Maps and elevation"]
  node_canvas["Map canvas<br/>[CCanvas.cpp]"]
  node_draw["GIS drawing<br/>[CGisDraw.cpp]"]
  node_mapsources["Map sources"]
  node_dem["Elevation models"]
  node_geomath["Coordinate math<br/>[GeoMath.cpp]"]
end

subgraph group_planning["Planning and analysis"]
  node_trackroute["Tracks and routes"]
  node_waypoints["Waypoints and areas"]
  node_routing["Routing engines"]
  node_analysis["Track analysis"]
end

subgraph group_integration["Data integration"]
  node_devices["GPS device support<br/>[IDevice.cpp]"]
  node_fit["Garmin FIT codec<br/>[fit_decode.cpp]"]
end

node_user(("GPS user"))
node_externalmaps["Map data"]
node_externalrouting(("Routing services"))
node_gpsdevice(("GPS device"))

node_user -->|"starts"| node_entry
node_entry -->|"opens"| node_window
node_user -->|"uses"| node_window
node_window -->|"manages"| node_workspace
node_workspace -->|"organizes"| node_gisdb
node_gisdb -->|"persists"| node_dbbackends
node_window -->|"displays"| node_canvas
node_canvas -->|"renders"| node_draw
node_draw -->|"reads items"| node_workspace
node_workspace -->|"organizes"| node_trackroute
node_workspace -->|"organizes"| node_waypoints
node_canvas -->|"displays"| node_mapsources
node_mapsources -->|"reads maps"| node_externalmaps
node_canvas -->|"shows elevation"| node_dem
node_dem -->|"uses coordinates"| node_geomath
node_trackroute -.->|"requests routes"| node_routing
node_routing -.->|"routes via"| node_externalrouting
node_trackroute -->|"supports analysis"| node_analysis
node_devices -->|"transfers data"| node_gpsdevice
node_devices -.->|"uses codec"| node_fit
node_gpsdevice -->|"exchanges GPS data"| node_devices

click node_entry "https://github.com/maproom/qmapshack/blob/dev/src/qmapshack/main.cpp"
click node_window "https://github.com/maproom/qmapshack/blob/dev/src/qmapshack/CMainWindow.cpp"
click node_canvas "https://github.com/maproom/qmapshack/blob/dev/src/qmapshack/canvas/CCanvas.cpp"
click node_draw "https://github.com/maproom/qmapshack/blob/dev/src/qmapshack/gis/CGisDraw.cpp"
click node_workspace "https://github.com/maproom/qmapshack/blob/dev/src/qmapshack/gis/CGisWorkspace.cpp"
click node_gisdb "https://github.com/maproom/qmapshack/blob/dev/src/qmapshack/gis/CGisDatabase.cpp"
click node_dbbackends "https://github.com/maproom/qmapshack/tree/dev/src/qmapshack/gis/db"
click node_trackroute "https://github.com/maproom/qmapshack/tree/dev/src/qmapshack"
click node_waypoints "https://github.com/maproom/qmapshack/tree/dev/src/qmapshack/gis"
click node_routing "https://github.com/maproom/qmapshack/tree/dev/src/qmapshack"
click node_analysis "https://github.com/maproom/qmapshack/tree/dev/src/qmapshack"
click node_mapsources "https://github.com/maproom/qmapshack/tree/dev/src/qmapshack"
click node_dem "https://github.com/maproom/qmapshack/tree/dev/src/qmapshack/dem"
click node_geomath "https://github.com/maproom/qmapshack/blob/dev/src/common/gis/GeoMath.cpp"
click node_devices "https://github.com/maproom/qmapshack/blob/dev/src/qmapshack/device/IDevice.cpp"
click node_fit "https://github.com/maproom/qmapshack/blob/dev/3rdparty/GarminFitSdk/cpp/fit_decode.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_window,node_user toneBlue
class node_workspace,node_gisdb,node_dbbackends toneAmber
class node_canvas,node_draw,node_mapsources,node_dem,node_geomath toneMint
class node_trackroute,node_waypoints,node_routing,node_analysis toneRose
class node_devices,node_fit,node_externalmaps,node_externalrouting,node_gpsdevice toneIndigo
```

## Components

### Desktop application

- [Application entry](https://github.com/maproom/qmapshack/blob/dev/src/qmapshack/main.cpp): `src/qmapshack/main.cpp`
- [Main window](https://github.com/maproom/qmapshack/blob/dev/src/qmapshack/CMainWindow.cpp): `src/qmapshack/CMainWindow.cpp`

### GIS workspace

- [GIS workspace](https://github.com/maproom/qmapshack/blob/dev/src/qmapshack/gis/CGisWorkspace.cpp): `src/qmapshack/gis/CGisWorkspace.cpp`
- [GIS database](https://github.com/maproom/qmapshack/blob/dev/src/qmapshack/gis/CGisDatabase.cpp): `src/qmapshack/gis/CGisDatabase.cpp`
- [Database backends](https://github.com/maproom/qmapshack/tree/dev/src/qmapshack/gis/db): `src/qmapshack/gis/db`

### Maps and elevation

- [Map canvas](https://github.com/maproom/qmapshack/blob/dev/src/qmapshack/canvas/CCanvas.cpp): `src/qmapshack/canvas/CCanvas.cpp`
- [GIS drawing](https://github.com/maproom/qmapshack/blob/dev/src/qmapshack/gis/CGisDraw.cpp): `src/qmapshack/gis/CGisDraw.cpp`
- [Map sources](https://github.com/maproom/qmapshack/tree/dev/src/qmapshack): `src/qmapshack`
- [Elevation models](https://github.com/maproom/qmapshack/tree/dev/src/qmapshack/dem): `src/qmapshack/dem`
- [Coordinate math](https://github.com/maproom/qmapshack/blob/dev/src/common/gis/GeoMath.cpp): `src/common/gis/GeoMath.cpp`

### Planning and analysis

- [Tracks and routes](https://github.com/maproom/qmapshack/tree/dev/src/qmapshack): `src/qmapshack`
- [Waypoints and areas](https://github.com/maproom/qmapshack/tree/dev/src/qmapshack/gis): `src/qmapshack/gis`
- [Routing engines](https://github.com/maproom/qmapshack/tree/dev/src/qmapshack): `src/qmapshack`
- [Track analysis](https://github.com/maproom/qmapshack/tree/dev/src/qmapshack): `src/qmapshack`

### Data integration

- [GPS device support](https://github.com/maproom/qmapshack/blob/dev/src/qmapshack/device/IDevice.cpp): `src/qmapshack/device/IDevice.cpp`
- [Garmin FIT codec](https://github.com/maproom/qmapshack/blob/dev/3rdparty/GarminFitSdk/cpp/fit_decode.cpp): `3rdparty/GarminFitSdk/cpp/fit_decode.cpp`

### Other components

- **GPS user**
- **Map data**
- **Routing services**
- **GPS device**

## Connections

- GPS user → Application entry: starts
- Application entry → Main window: opens
- GPS user → Main window: uses
- Main window → GIS workspace: manages
- GIS workspace → GIS database: organizes
- GIS database → Database backends: persists
- Main window → Map canvas: displays
- Map canvas → GIS drawing: renders
- GIS drawing → GIS workspace: reads items
- GIS workspace → Tracks and routes: organizes
- GIS workspace → Waypoints and areas: organizes
- Map canvas → Map sources: displays
- Map sources → Map data: reads maps
- Map canvas → Elevation models: shows elevation
- Elevation models → Coordinate math: uses coordinates
- Tracks and routes → Routing engines: requests routes
- Routing engines → Routing services: routes via
- Tracks and routes → Track analysis: supports analysis
- GPS device support → GPS device: transfers data
- GPS device support → Garmin FIT codec: uses codec
- GPS device → GPS device support: exchanges GPS data