GeoConnect

→ Open GeoConnect

A guide to Japan for American travellers. Click any of Japan's eight regions to read why its culture works the way it does, see the places worth visiting, and compare Japanese customs against the US region that most resembles it.

Built with Dioxus (Rust), and it runs in the browser — no install, no sign-up.

Downloads

The web version above is the easiest way in. Native installers are on the Releases page:

• Android APK — download GeoConnect.apk, open it on your phone, and allow "install unknown apps" when prompted (normal for a sideloaded app, not a sign of a problem).
• Windows MSI — download the .msi installer and run it.

Architecture

The app ships its content as data. assets/content.json is a snapshot of the Postgres content tables, compiled into the binary, and every build — web, desktop, and Android — reads from it. Nothing the app ships connects to a database.

That replaced an earlier design where each binary opened a direct Postgres connection, which meant a credential had to travel inside every APK and MSI where anyone could pull it out with strings. It also made a browser build impossible, since WASM cannot speak the Postgres wire protocol. Shipping the content as data removes both problems at once.

Postgres is still where the content is authored. Refresh the snapshot with:

cargo run --features db --bin dump_content

That is the only build that touches the database, and build.rs only asks for a DATABASE_URL when the db feature is on — so a normal build (and CI) needs no credential at all. The guard requiring the least-privilege geoconnect_readonly role is still enforced for that path.

Photos

Every photograph is a freely licensed file from Wikimedia Commons, downloaded and attributed by scripts/fetch_images.py, which regenerates src/images.rs and the credits list in src/image_credits.rs. The in-app Credits page lists each photo's author and licence.

python3 scripts/fetch_images.py     # re-download photos and rebuild the credits
python3 scripts/gen_map_data.py     # re-measure the map's region hitboxes

Deployment

Pushes to main build the web bundle and publish it to GitHub Pages via .github/workflows/deploy.yml. The site is static, so it needs no server and no secrets.

Because Pages serves files rather than routes, scripts/gen_route_pages.py writes a real page for every route in the app, so a shared link to a region or place answers 200 instead of falling through to 404.html.

One-time setup, already done for this repo: in Settings → Pages, set Source to GitHub Actions. A fork needs this too — the workflow cannot enable Pages for itself, because GITHUB_TOKEN is not allowed to create a Pages site.

Build from source

Requirements

• Rust + Cargo (stable toolchain)
• Dioxus CLI: cargo install dioxus-cli --locked No database credential is needed to build the app. A .env containing DATABASE_URL=<geoconnect_readonly postgres connection string> is required only to refresh the content snapshot (--features db); the build fails unless that URL uses the geoconnect_readonly role, so an admin credential cannot end up in a distributable. Admin credentials belong in .env.admin (gitignored, never read by the build).

Development build & run

cargo install dioxus-cli --locked
dx serve                       # desktop
dx serve --platform web        # in a browser

Web bundle (what gets deployed)

dx bundle --platform web --release
# output: target/dx/geoconnect/release/web/public

Android APK

dx bundle --release --platform android
scripts/patch_android_icon.sh   # dx doesn't wire the bundle icon through to Android yet
dx bundle --release --platform android   # repackage with the patched icon

Windows MSI installer

Build natively on Windows (not inside WSL/Linux) — the desktop app uses a native webview, which cross-compiles unreliably.

1. Install prerequisites on the Windows machine:
   • Rust: https://rustup.rs
   • Dioxus CLI: cargo install dioxus-cli --locked
2. Copy/clone this source tree onto that machine.
3. Build the release installer:

   dx bundle --release --platform windows --package-types msi
   

   (The first run automatically downloads the WiX Toolset needed to build the .msi.)
4. The finished installer will be at:

   target\dx\geoconnect\release\windows\app\bundle\msi\*.msi
   

Database Schema

• regions — the regions of Japan (id, name, overview)
• categories — content topics like History, Food & Dining, Etiquette (id, name)
• facts — cultural/historical content per region and category (id, region_id, category_id, title, body)
• comparisons — US vs. Japanese custom comparisons per region (id, category_id, region_id, title, us_practice, jp_practice, us_region, key_difference)
• places — notable places to visit per region (id, region_id, name, kind, tagline, overview)
• place_highlights — highlights for each place (id, place_id, category, title, body)
• travel_prep — region-specific travel preparation guidance (id, region_id, category, title, body)

These tables are the authoring source; dump_content snapshots them into assets/content.json, which is what the app actually reads.

The read-only role used to take that snapshot is created by scripts/readonly_role.sql (run it as the database admin; set the role's password separately so no credential lives in the repo).