= Architecture
:toc:
:toclevels: 2

== Overview

MapTool is a Sinatra web application. The desktop build does not
reimplement anything natively — it wraps the same Sinatra app in a
https://tauri.app[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.

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

== Directory layout

[cols="1,3"]
|===
| 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 https://tauri.app/develop/sidecar/[sidecar] binary
(for example, produced with https://github.com/tebako/tebako[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.