# bmwcarit/barefoot architecture

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

- Interactive diagram: https://gitdiagram.com/bmwcarit/barefoot
- Repository: https://github.com/bmwcarit/barefoot

## Overview

##### Project type and purpose
- Barefoot is an open-source, Java-based map matching library and a set of stand-alone servers (matcher and tracker) plus auxiliary tools (map server, monitor UI, submission scripts).
- It provides both offline (batch) and online (real-time) Hidden Markov Model (HMM) map matching on OpenStreetMap data, a suite of spatial/geometric operations, cluster analysis (DBSCAN), routing (Dijkstra), and support for parallel/distributed execution.

##### File structure
- Top-level directories
- config: properties for servers and map loading
- deps: third-party licenses, manually vendored jars (ESRI, GeographicLib, Jackson, JeroMQ, etc.)
- Dockerfile, Postgres/PostGIS configuration, import scripts, Python map tools (bfmap.py, osm2ways.py)
- src: Java code organized under com.bmwcarit.barefoot
– analysis (DBSCAN)
– markov (HMM core: states, transitions)
– matcher (offline matcher API and MatcherServer)
– tracker (online matcher API and TrackerServer)
– road, roadmap (in-memory map data structures, loaders)
– spatial (geometric operators, quad-trees)
– topology (graph, Dijkstra router)
– scheduler (parallel task scheduling)
– util (common I/O, server base classes, JDBC sources)
- util/monitor: NodeJS web monitor (ZeroMQ → Socket.io → browser)
- util/submit: Python scripts for batch and streaming submission to servers
- wiki: markdown documentation

##### README for additional insights
- Confirms architecture:
- “Docker-based map server” (PostgreSQL + PostGIS container)
- “Standalone matcher server” (Java JAR, REST-like API)
- “Standalone tracker server” (Java JAR, ZeroMQ for push)
- “Monitor” (NodeJS web app visualizing tracker output)
- Library API for JVM integration (Hadoop, Spark, Storm)
- Key technologies: Java 7+, Maven, ZeroMQ (JeroMQ), PostgreSQL JDBC, ESRI Geometry API, GeographicLib, Jackson JSON.

##### Detail without overthinking
- Server, module layer, and communication channel
- Docker map server, matcher server, tracker server, monitor UI, and submission scripts

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Data Store / Map Server"
        DB["PostgreSQL + PostGIS"]:::dataStore
        subgraph "OSM Import Tools"
            ImportShell["import.sh"]:::external
            BFMap["bfmap.py"]:::external
            Osm2ways["osm2ways.py"]:::external
        end
    end

    subgraph "Java Library Modules"
        subgraph "Data Layer"
            Loader["roadmap.Loader"]:::java
            PostgresSource["util.PostgresSource"]:::java
        end
        subgraph "Geometry / Spatial Layer"
            ESRI["ESRI Geometry API"]:::external
            GeoLib["GeographicLib"]:::external
            QuadTree["QuadTreeIndex"]:::java
            SpatialOp["SpatialOperator"]:::java
        end
        subgraph "Analysis Layer"
            DBSCAN["analysis.DBSCAN"]:::java
            Dijkstra["topology.Dijkstra"]:::java
            HMMFactory["markov.Factory"]:::java
            KState["markov.KState"]:::java
            StateTrans["markov.StateTransition"]:::java
            StaticSched["scheduler.StaticScheduler"]:::java
            Scheduler["scheduler.Scheduler"]:::java
        end
        subgraph "Service Layer"
            MatcherServer["MatcherServer (HTTP/JSON)"]:::service
            MatcherFactory["MatcherFactory"]:::java
            TrackerServer["TrackerServer (ZeroMQ)"]:::service
            TrackerControl["TrackerControl"]:::java
        end
    end

    subgraph "Monitor UI"
        MonitorServer["monitor.js"]:::ui
        MonitorIndex["index.html"]:::ui
        MonitorPkg["package.json"]:::ui
    end

    subgraph "Submission CLI Scripts"
        BatchCLI["batch.py"]:::external
        StreamCLI["stream.py"]:::external
    end

    BigData["BigData Frameworks<br/>(Hadoop/Spark/Storm)"]:::bigdata

    Browser["Browser UI"]:::ui

    %% Data flows
    ImportShell -->|feeds| DB
    BFMap -->|feeds| DB
    Osm2ways -->|feeds| DB

    DB -->|JDBC 5432| Loader
    DB -->|JDBC 5432| PostgresSource

    Loader --> QuadTree
    Loader --> SpatialOp
    PostgresSource --> QuadTree
    PostgresSource --> SpatialOp

    ESRI --> QuadTree
    GeoLib --> QuadTree
    ESRI --> SpatialOp
    GeoLib --> SpatialOp

    QuadTree --> DBSCAN
    SpatialOp --> DBSCAN
    QuadTree --> Dijkstra
    SpatialOp --> Dijkstra
    QuadTree --> HMMFactory
    SpatialOp --> HMMFactory

    DBSCAN --> MatcherServer
    Dijkstra --> MatcherServer
    HMMFactory --> MatcherServer
    StaticSched --> MatcherServer
    Scheduler --> MatcherServer

    DBSCAN --> TrackerServer
    Dijkstra --> TrackerServer
    HMMFactory --> TrackerServer
    StaticSched --> TrackerServer
    Scheduler --> TrackerServer

    DB -->|JDBC 5432| MatcherServer
    DB -->|JDBC 5432| TrackerServer

    BatchCLI -->|HTTP/JSON 1234| MatcherServer
    StreamCLI -->|ZeroMQ 1235| TrackerServer

    TrackerServer -->|PUB ZeroMQ 1235| MonitorServer
    MonitorServer -->|Socket.io| Browser

    MatcherServer -->|Library API| BigData
    TrackerServer -->|Library API| BigData

    %% Styles
    classDef dataStore fill:#9f6,stroke:#333,stroke-width:1px
    classDef java fill:#6af,stroke:#333,stroke-width:1px
    classDef service fill:#4a8,stroke:#333,stroke-width:1px
    classDef external fill:#fa0,stroke:#333,stroke-width:1px
    classDef ui fill:#a6f,stroke:#333,stroke-width:1px
    classDef bigdata fill:#ccc,stroke:#333,stroke-width:1px

    %% Click Events
    click DB "https://github.com/bmwcarit/barefoot/tree/master/map/Dockerfile"
    click DB "https://github.com/bmwcarit/barefoot/tree/master/map/pgsql/"
    click ImportShell "https://github.com/bmwcarit/barefoot/blob/master/map/osm/import.sh"
    click BFMap "https://github.com/bmwcarit/barefoot/blob/master/map/tools/bfmap.py"
    click Osm2ways "https://github.com/bmwcarit/barefoot/blob/master/map/tools/osm2ways.py"
    click Loader "https://github.com/bmwcarit/barefoot/blob/master/src/main/java/com/bmwcarit/barefoot/roadmap/Loader.java"
    click PostgresSource "https://github.com/bmwcarit/barefoot/blob/master/src/main/java/com/bmwcarit/barefoot/util/PostgresSource.java"
    click ESRI "https://github.com/bmwcarit/barefoot/tree/master/deps/esri-geometry-api/"
    click GeoLib "https://github.com/bmwcarit/barefoot/tree/master/deps/geographiclib/"
    click QuadTree "https://github.com/bmwcarit/barefoot/blob/master/src/main/java/com/bmwcarit/barefoot/spatial/QuadTreeIndex.java"
    click SpatialOp "https://github.com/bmwcarit/barefoot/blob/master/src/main/java/com/bmwcarit/barefoot/spatial/SpatialOperator.java"
    click DBSCAN "https://github.com/bmwcarit/barefoot/blob/master/src/main/java/com/bmwcarit/barefoot/analysis/DBSCAN.java"
    click Dijkstra "https://github.com/bmwcarit/barefoot/blob/master/src/main/java/com/bmwcarit/barefoot/topology/Dijkstra.java"
    click HMMFactory "https://github.com/bmwcarit/barefoot/blob/master/src/main/java/com/bmwcarit/barefoot/markov/Factory.java"
    click KState "https://github.com/bmwcarit/barefoot/blob/master/src/main/java/com/bmwcarit/barefoot/markov/KState.java"
    click StateTrans "https://github.com/bmwcarit/barefoot/blob/master/src/main/java/com/bmwcarit/barefoot/markov/StateTransition.java"
    click StaticSched "https://github.com/bmwcarit/barefoot/blob/master/src/main/java/com/bmwcarit/barefoot/scheduler/StaticScheduler.java"
    click Scheduler "https://github.com/bmwcarit/barefoot/blob/master/src/main/java/com/bmwcarit/barefoot/scheduler/Scheduler.java"
    click MatcherServer "https://github.com/bmwcarit/barefoot/blob/master/src/main/java/com/bmwcarit/barefoot/matcher/MatcherServer.java"
    click MatcherFactory "https://github.com/bmwcarit/barefoot/blob/master/src/main/java/com/bmwcarit/barefoot/matcher/MatcherFactory.java"
    click TrackerServer "https://github.com/bmwcarit/barefoot/blob/master/src/main/java/com/bmwcarit/barefoot/tracker/TrackerServer.java"
    click TrackerControl "https://github.com/bmwcarit/barefoot/blob/master/src/main/java/com/bmwcarit/barefoot/tracker/TrackerControl.java"
    click MonitorPkg "https://github.com/bmwcarit/barefoot/blob/master/util/monitor/package.json"
    click MonitorServer "https://github.com/bmwcarit/barefoot/blob/master/util/monitor/monitor.js"
    click MonitorIndex "https://github.com/bmwcarit/barefoot/blob/master/util/monitor/public/index.html"
    click BatchCLI "https://github.com/bmwcarit/barefoot/blob/master/util/submit/batch.py"
    click StreamCLI "https://github.com/bmwcarit/barefoot/blob/master/util/submit/stream.py"
```
