maptool/docs/architecture.adoc

Architecture

Table of Contents

• Overview
• Directory layout
• Desktop shell (Tauri)
  • Known limitation: production packaging
• Networking

Overview

MapTool is a Sinatra web application. The desktop build does not reimplement anything natively — it wraps the same Sinatra app in a Tauri window, which is the standard way to ship a non-JavaScript backend as a desktop app with Tauri: the Rust shell owns the native window and starts the web server as a local process; the window then simply loads http://127.0.0.1:4567 as if it were a regular page.

+----------------------------+
| Tauri window (WebView)     |
|  loads http://127.0.0.1:PORT
+--------------+-------------+
               |
               v
+----------------------------+
| Sinatra app (Puma)         |
|  app.rb / config.ru        |
+----------------------------+

Directory layout

Path	Purpose
app.rb, config.ru	Sinatra application and Rack entry point.
config/puma.rb	Puma server configuration (binds to 127.0.0.1 only — the app is local-only, not exposed on the network).
public/, views/	Frontend assets and Sinatra templates. The map view uses Leaflet.
src-tauri/	The Tauri (Rust) desktop shell.
docs/	Project documentation, in AsciiDoc.

Desktop shell (Tauri)

In development, src-tauri/tauri.conf.json sets beforeDevCommand to start Puma, and devUrl points the window at it. Running the dev build (see docs/development.adoc) starts both together.

In a packaged build there is no beforeDevCommand hook, so src-tauri/src/lib.rs starts the server itself (bundle exec puma) next to the bundled resources when the app launches, and stops it when the window closes.

Known limitation: production packaging

The packaged-build server spawn currently assumes a Ruby + Bundler installation already present on the machine running the app. That is fine for internal or developer builds, but not for a distributable, self-contained desktop app.

Shipping a real self-contained build would mean embedding a Ruby runtime as a Tauri sidecar binary (for example, produced with tebako), instead of relying on the system Ruby. That decision — and the resulting sidecar build step — is not implemented yet and should be revisited before any real distribution build.

Networking

The Sinatra server only binds to 127.0.0.1. It is not meant to be reachable from other machines; the Tauri window talks to it over loopback only.