# julienperret/mapmatcher architecture

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

- Interactive diagram: https://gitdiagram.com/julienperret/mapmatcher
- Repository: https://github.com/julienperret/mapmatcher

## Overview

1. **Repository purpose**
   - This is a small Java library for **map matching GPS traces onto a trail/road network**.
   - Its main job is to turn noisy GPS observations into a best-fit path using the **Hidden Markov Model (HMM) map matching algorithm** from Newson and Krumm.

2. **Primary architectural shape**
   - The repo is not a full application; it is a **library plus a thin command-line wrapper**.
   - The library is packaged as a single runnable JAR with dependencies, intended to be called externally rather than embedded in a larger Java app.

3. **Core domain subsystem**
   - `src/main/java/mapmatcher/HikingTrailMapMatcher.java` is the likely core implementation class.
   - Based on the README, this class is responsible for the actual matching logic: reading spatial data, running the HMM-based algorithm, and producing matched results.

4. **Command-line / integration boundary**
   - `src/main/java/mapmatcher/MatchHikingTrail.java` is the entry point used from the shell and, indirectly, from R.
   - It accepts file paths and tuning parameters, then invokes the core matcher. This is the boundary where external callers cross into the Java code.

5. **Data flow through the system**
   - Input comes from two spatial datasets: a **GPS file** and a **network file**.
   - The CLI passes those inputs plus algorithm parameters to the matcher.
   - The matcher computes the aligned path and writes a tabular output file, which the caller can read back as a table.

6. **Input/output contract**
   - The README shows inputs are expected as **shapefiles** for both GPS observations and the route network.
   - Output is written as a **CSV-like table** that R reads using `read.table(..., header=TRUE)`.
   - So the architectural boundary is file-based rather than in-memory or service-based.

7. **Algorithmic dependency**
   - The implementation relies on the **GeOxygene** library for the HMM map matching algorithm.
   - That means the repository’s core logic is thin glue around a GIS/mapping library rather than a custom algorithm implementation from scratch.

8. **Parameterization layer**
   - The exposed parameters in the README — `sigmaZ`, `selection`, `beta`, and `distanceLimit` — are tuning knobs for the HMM matcher.
   - Architecturally, these parameters flow from the CLI/R wrapper into the matching engine and affect candidate selection and scoring.

9. **R integration boundary**
   - The project is explicitly designed to be called from **R**.
   - The README’s example wraps the Java CLI in an R function, showing the intended usage pattern: R orchestrates execution, Java performs matching, and R loads the output table.

10. **Build and packaging subsystem**
   - The project uses **Maven** (`pom.xml`) to compile and package the library.
   - The expected artifact is a **“jar with dependencies”**, which indicates a shaded/uber-JAR style distribution to simplify calling from R or the command line.

11. **Operational/runtime model**
   - There is no server, database, or background worker in the repository.
   - The runtime is a simple **batch process**: read files, match, write results, exit.

12. **Tooling and CI**
   - `.travis.yml` and the README badge show the project is wired for **Travis CI**.
   - This is a build verification layer only; it does not change runtime architecture, but it confirms the project is intended to be continuously built and tested.

13. **External dependency boundaries**
   - The important external dependency is **GeOxygene** for GIS/map-matching capabilities.
   - The repository also assumes the presence of standard Java build tooling and, for users, R as the downstream consumer.

14. **How to draw the architecture**
   - A good diagram would show:
     - R or shell caller on the left
     - the CLI entrypoint as the boundary
     - the core map-matching engine in the center
     - GeOxygene as an internal third-party library beneath the core
     - shapefile inputs entering the system and matched tabular output leaving it
   - There are no additional subsystems such as persistence, networking, or UI to include.

Main entry points: [`src/main/java/mapmatcher/HikingTrailMapMatcher.java`](https://github.com/julienperret/mapmatcher/blob/master/src/main/java/mapmatcher/HikingTrailMapMatcher.java) (HikingTrailMapMatcher), [`src/main/java/mapmatcher/MatchHikingTrail.java`](https://github.com/julienperret/mapmatcher/blob/master/src/main/java/mapmatcher/MatchHikingTrail.java) (MatchHikingTrail), [`pom.xml`](https://github.com/julienperret/mapmatcher/blob/master/pom.xml) (Maven build), [`.travis.yml`](https://github.com/julienperret/mapmatcher/blob/master/.travis.yml) (Travis CI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_cli["MatchHikingTrail<br/>CLI entrypoint"]
  node_matcher["HikingTrailMapMatcher<br/>matching engine"]
  node_params(("Tuning params<br/>HMM settings"))
end

subgraph group_build["Build & CI"]
  node_maven["Maven build<br/>packaging<br/>[pom.xml]"]
  node_travis["Travis CI<br/>ci config<br/>[.travis.yml]"]
end

subgraph group_external["External"]
  node_r_caller["R caller<br/>downstream orchestrator"]
  node_shell_user["Shell user<br/>batch caller"]
  node_gps_input["GPS file<br/>shapefile input"]
  node_network_input["Network file<br/>shapefile input"]
  node_matched_output["Matched table<br/>tabular output"]
  node_geoxygene{{"GeOxygene<br/>third-party GIS library"}}
end

node_r_caller -->|"invokes"| node_cli
node_shell_user -->|"runs"| node_cli
node_cli -->|"delegates"| node_matcher
node_gps_input -->|"input"| node_matcher
node_network_input -->|"input"| node_matcher
node_params -->|"configures"| node_matcher
node_matcher -->|"uses"| node_geoxygene
node_matcher -->|"writes"| node_matched_output
node_r_caller -->|"reads"| node_matched_output
node_maven -->|"builds"| node_cli
node_maven -->|"builds"| node_matcher
node_travis -->|"verifies"| node_maven

click node_cli "https://github.com/julienperret/mapmatcher/blob/master/src/main/java/mapmatcher/MatchHikingTrail.java"
click node_matcher "https://github.com/julienperret/mapmatcher/blob/master/src/main/java/mapmatcher/HikingTrailMapMatcher.java"
click node_maven "https://github.com/julienperret/mapmatcher/blob/master/pom.xml"
click node_travis "https://github.com/julienperret/mapmatcher/blob/master/.travis.yml"

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_cli,node_matcher,node_params toneBlue
class node_maven,node_travis toneAmber
class node_r_caller,node_shell_user,node_gps_input,node_network_input,node_matched_output,node_geoxygene toneMint
```

## Components

### Runtime

Batch map-matching flow

- [MatchHikingTrail](https://github.com/julienperret/mapmatcher/blob/master/src/main/java/mapmatcher/MatchHikingTrail.java): CLI entrypoint · Thin command-line boundary that parses arguments and launches matching. · `src/main/java/mapmatcher/MatchHikingTrail.java`
- [HikingTrailMapMatcher](https://github.com/julienperret/mapmatcher/blob/master/src/main/java/mapmatcher/HikingTrailMapMatcher.java): matching engine · Core HMM map-matching implementation and file-based processing logic. · `src/main/java/mapmatcher/HikingTrailMapMatcher.java`
- **Tuning params**: HMM settings · sigmaZ, selection, beta, and distanceLimit flow into the matcher.

### Build & CI

Packaging and verification

- [Maven build](https://github.com/julienperret/mapmatcher/blob/master/pom.xml): packaging · Compiles and packages the runnable jar with dependencies. · `pom.xml`
- [Travis CI](https://github.com/julienperret/mapmatcher/blob/master/.travis.yml): ci config · Continuous integration configuration for build verification. · `.travis.yml`

### External

Downstream and third-party boundaries

- **R caller**: downstream orchestrator · R wraps the Java CLI and reads the tabular output back in.
- **Shell user**: batch caller · Command-line entry point for running the matcher directly.
- **GPS file**: shapefile input · Observed GPS trace data provided as a file.
- **Network file**: shapefile input · Trail or road network used as the matching graph.
- **Matched table**: tabular output · CSV-like results written for consumption by R or other callers.
- **GeOxygene**: third-party GIS library · External GIS library providing map-matching and spatial capabilities.

## Connections

- R caller → MatchHikingTrail: invokes · R launches the Java CLI wrapper.
- Shell user → MatchHikingTrail: runs · The matcher can also be run directly from the shell.
- MatchHikingTrail → HikingTrailMapMatcher: delegates · CLI forwards the file paths and matching settings into the core engine.
- GPS file → HikingTrailMapMatcher: input · Observed GPS observations are consumed by the matcher.
- Network file → HikingTrailMapMatcher: input · Route or trail network is read by the matcher.
- Tuning params → HikingTrailMapMatcher: configures · HMM tuning values affect candidate selection and scoring.
- HikingTrailMapMatcher → GeOxygene: uses · Core matching logic relies on the GeOxygene GIS library.
- HikingTrailMapMatcher → Matched table: writes · Matched path results are emitted as a table-like file.
- R caller → Matched table: reads · R loads the produced table for downstream analysis.
- Maven build → MatchHikingTrail: builds · Maven compiles the CLI class into the packaged artifact.
- Maven build → HikingTrailMapMatcher: builds · Maven packages the core matcher into the runnable jar.
- Travis CI → Maven build: verifies · CI runs the Maven build to check the repository.