Alpha Changelog

Development log for Ultreia. We're in early alpha - expect rough edges! You're cordially invited to kick the tires of this app, as much as you'd like. Your content will not be lost as we add more features and spray the bugs with borax. If you find a bug, you may report it to mailto:hola@ultreia.me or find other ways to contact us on our contacts page.

v0.16.5 - Admin Improvements

• Added QR code to owner access section for easy on-trail sharing
• Improved mobile layout for review changes interface
• Restyled support page

v0.16.4 - Internal Improvements

• Fixed URL extraction in albergue data enrichment (full paths now preserved)

v0.16.0 - Internal Cleanup

• Consolidated icon system for better maintainability
• Fixed icon display issues in admin interface

v0.14.2 - Candidate Editor QOL

• Fixed eye icon visibility in candidate list (now white on primary background)
• Added "Approve & Edit" button to candidate list and detail views

v0.14.1 - Support Page

• Added "Buy us a Coffee" link in menu footer
• New Support page with Ko-Fi integration
• Two-column layout on desktop, stacked on mobile

v0.14.0 - Help Out Enhancements

• Stamp submissions now support photo uploads
• Added nickname field to stamp form (persisted in browser for repeat submissions)
• Admin can view submitted stamp photos in review queue
• Photos automatically transfer to POI when created from submission
• Submission marked as approved when POI is created

v0.13.1 - Albergue Deduplication Tool

• New admin page for detecting and merging duplicate albergues
• Proximity detection finds albergues within 20m of each other
• Fuzzy name matching finds similar names (>40% similarity) within 500m
• Side-by-side comparison view with field-by-field merge selection
• Map preview showing both locations
• Transfers images and reviews to merged record
• Dismiss pairs permanently to hide false positives
• Route filter on Leaf & Shell list with localStorage persistence
• Added town_name field to POIs for proper Leaf & Shell grouping

v0.13.0 - Albergue Candidate Staging System

• New admin queue for reviewing OSM albergue candidates before import
• Import candidates from Geofabrik extracts with ./ultreia import-albergue-candidates <route>
• Distance-based color coding: green (<50m), yellow (50-250m), red (>250m) from route
• Bulk approve/reject actions for quick triage
• Extracts OSM data on approval: beds, phone, website, email, facebook, address, features
• Smart phone number selection: prefers mobile numbers for Spain (+34 6/7xx) and Portugal (+351 9xx)
• Added Facebook field to albergues with icon in contact actions
• Auto-numbered slugs for duplicate albergue names (e.g., "albergue-de-peregrinos-2")

v0.12.0 - Route-Filtered POI Display

• POI markers now filter to selected route's bounding box
• Keeps full data cached for offline use, filters client-side for display
• Console shows filtered/total counts (e.g., "fountains: 234/938")
• "All Routes" still shows everything

v0.11.1 - Full Offline Support

• All POI data (fountains, albergues, POIs) now loads once and caches in memory
• Pan/zoom is instant with zero network requests after initial load
• ~300KB of marker data cached for offline use (938 fountains, 461 albergues, 31 POIs)
• Combined with route caching, map works fully offline after first load
• Ideal for pilgrims using airplane mode or in areas with spotty connectivity

v0.11.0 - Fountain Importer & Pan Performance

• New ./ultreia find-fountains command to import fountains from OpenStreetMap
• Walks route in 4km steps, queries 5km radius, filters to fountains within 50m
• Extracts potability from OSM tags (only explicit drinking_water=yes/no)
• OSM sync with 6-hour buffer prevents syncing freshly imported data
• New ./ultreia sync-osm command for syncing local changes to OpenStreetMap
• Routes now load once and stay cached during pan/zoom (major performance improvement)
• Pan operations no longer reload route data, only POI markers

v0.10.0 - Multi-Route & Drawer Redesign

• Route bounding box filtering: map data now loads only within selected route area
• Faster map performance when a specific route is selected
• Menu button moved to floating layer bar using Ultreia icon
• Redesigned drawer with Primary Actions and Secondary Utilities sections
• My Route selector and Leaf & Shell access now in prominent action cards
• Compact 3x4 grid for secondary navigation (responsive: 3 columns mobile, 4 desktop)
• Footer with cache controls pushed to bottom of drawer

v0.9.0 - Route Colors & Variants

• Per-route color system with 8-color palette for map display
• Three-tier route classification: Main, Major Variant, Minor Variant
• Major variants (multi-day routes like Coastal, Central) get solid colored lines
• Minor variants (short diversions) stay dashed blue for clear visual language
• Color picker with swatches in admin route form
• Grouped route list in admin showing hierarchy with variants nested under parents
• Route colors visible throughout admin UI with color dots

v0.8.0 - Help Out & Tile Automation

• Help Out page for crowdsourced data contributions
• Tile refresh command: ./ultreia tiles:refresh extracts tiles from Protomaps
• Tile coverage auto-expands when new routes are added
• New tile commands: tiles:info, tiles:sync
• Photo gallery with lightbox on detail pages
• Shared partials for action cards, map cards, reviews

v0.7.0 - Wayfinder's Companion Design

• New visual design language for detail pages and popups
• Redesigned map popups for fountains, albergues, and POIs
• Redesigned albergue detail page with hero images and stat pills
• Redesigned POI detail page with type-colored headers
• Redesigned fountain correction page with back button
• Leaf & Shell cards now link to the full list
• Fixed map loading issues when navigating back
• Improved service worker reliability for offline tiles

v0.6.5 - Leaf & Shell List

• New Leaf & Shell page listing all vegan/vegetarian-friendly stops
• Entries ordered by position along each Camino route
• Grouped by town with beds, rooms, prices for albergues
• Dietary status badges (Strictly Vegan, Vegetarian, Offers options)
• Featured images displayed when available
• Public submission form for suggesting new places
• Auto-regeneration of list when entries are added/removed
• Leaf & Shell section added to map menu

v0.6.4 - POI Detail Pages

• Public detail pages for Points of Interest at /pois/:slug
• Type-specific header colors matching map markers
• Contact bar with phone, WhatsApp, email, website, Instagram
• Mini map with directions button
• Opening hours and description sections
• Reviews and ratings with same system as albergues
• "Details" button added to POI popups on map

v0.6.3 - Reviews & Ratings

• Users can now leave reviews and ratings on albergue pages
• Star rating (1-5) and/or text comment supported
• Average rating displayed on albergue detail page
• Only reviews with comments are shown publicly (ratings-only still count toward average)
• Admin reviews page to view and delete user reviews

v0.6.2 - Fountain Corrections

• Fountain popup redesigned: shows potability status prominently, removes redundant name
• Public correction page: users can submit potability corrections for fountains
• Admin submissions queue: review and approve/reject user corrections
• Pending submissions badge in admin sidebar
• Verified corrections will be sent to OpenStreetMap (coming soon)

v0.6.1 - Field Survey

• Add Field Survey page to admin (now the admin landing page)
• "Search Here" button uses GPS to find nearby items within 10km
• Search by town name with autocomplete
• Results show towns, albergues, fountains, and POIs sorted by distance
• Quick-add buttons for albergue/fountain/POI at current GPS location
• Distance display helper (formats meters to km when appropriate)

v0.6.0 - Image uploads

• Add image uploads for albergues, towns, and POIs
• Drag-and-drop or click-to-select upload interface in admin
• Automatic thumbnail, medium (800px), and large (1200px) generation
• WebP versions for all sizes (better compression)
• HEIC support for iPhone photos
• Gallery with drag-to-reorder and featured image selection
• Albergue detail page: hero image from featured photo or default
• Albergue detail page: booking button moved above policies
• Albergue detail page: green "no curfew" indicator

v0.5.2 - Admin improvements and polish

• Admin towns: route filter pills, sort by route order, show km distance
• Admin towns: features displayed as MDI icons (self-hosted for GDPR)
• Admin albergues: warning badges for "No Wifi" / "No Cards" when explicitly false
• Admin albergues: price fields accept ranges (e.g. "10-15")
• Server-side query caching for fountains, albergues, POIs (5 min by bbox)
• Remove default_scope from Trackpoint/Sector models
• BASEMAP_TILES env var for configurable tile filename
• Rename camino-frances.pmtiles → camino.pmtiles
• Fix table cell alignment and border issues

v0.5.1 - Performance optimizations

• Only load data for the active layer (reduces API calls by 75%)
• Add HTTP caching headers to API (5 min cache, 1 hour stale-while-revalidate)
• Add "My Route" selector in menu - filter map data to selected route only
• Route variants automatically included when parent route selected
• Add database indexes for frequently filtered columns

v0.5 - Points of Interest and enhanced map markers

• Add Points of Interest (POI) with full admin CRUD
• POI types: Monument, Shop, Food & Drink, Stamp, Museum, Church, Historical, Vista
• Type-specific colored icons on map (blue, purple, orange, brown, teal, indigo, amber, green)
• Leaf & Shell support for POIs (vegan/vegetarian friendly locations)
• Enhanced Leaf & Shell markers - larger size, VIP star badge for premium albergues
• POI layer toggle in floating bar with persistence
• POI fields: name, type, address, opening hours, description, contact info, website

v0.4.3 - Remember selected map layer

• Persist active layer (fountains/albergues/leafshell) in localStorage
• Restore layer selection when returning to map from detail pages
• Fix race condition when loading map data during initialization

v0.4.2 - Add pricing fields to albergue admin form

• Add pricing section with accommodation (bunk, single, double, triple), meals (breakfast, dinner), and laundry (washer, dryer) fields
• Conditionally show washer/dryer prices based on feature availability
• Currency-prefixed input fields with responsive grid layout

v0.4.1 - Alpha welcome popup and changelog

• Add reusable popup partial with mobile/desktop responsive design
• Show alpha welcome message with cookie-based dismissal
• Add changelog page and link in hamburger menu
• Fix Turbo navigation conflicts between layouts

v0.4.0 - Add albergues to map with public detail pages

• Add albergue markers to map with bed icon (amber circle)
• Use leafandshell.png icon for vegan/vegetarian albergues
• Create Leaf & Shell layer filter button in layer bar
• Add popup with name, beds, rooms, price, and Details button
• Create public albergue detail page at /albergues/:slug
  • Mobile-first design with amber header
  • Contact bar (Call, WhatsApp, Email, Web)
  • Interactive mini-map with native directions support
  • Policy cards, amenities grid, schedule, booking link
• Platform-aware directions: Apple Maps on iOS, geo: on Android
• Fix Turbo conflicts between map and detail page layouts
• Fix layer bar error for non-existent layers

v0.3.0 - Add local tile serving, markdown pages, and Caddy config

Local tile serving (saves CDN costs in development):
- TilesController with Range request support
- tiles.ultreia.me Caddy config for direct file serving
- tile_url helper switches between local/CDN by environment
- ./ultreia sync-tiles command for uploading to bunny.net

Markdown pages system:
- PagesController loads .md files from content/pages/
- Redcarpet gem for GitHub-flavored markdown
- /txt/:slug routes (about, help, settings)
- Clean layout with back button, styled content

Other fixes:
- Service worker routes all .pmtiles to tile handler (fixes 206 cache errors)
- data-turbo="false" on cross-layout links (fixes Turbo conflicts)

Fix N+1 queries, add MDI icons, improve layer bar styling

• Fix N+1 query in routes controller (use LEFT JOIN with COUNT)
• Fix N+1 query in sectors controller (use SQL subqueries for counts)
• Optimize map controller to pluck route IDs directly
• Add display-mode media queries for PWA vs browser positioning
• Replace letter icons with inline MDI SVGs (cup-water, bunk-bed, church)
• Make layer bar background more transparent (35% opacity)

Clean up menu drawer with centered logo

Add layer bar, hamburger menu, and iOS PWA improvements

• Floating bottom layer bar with F/A/P/Leaf&Shell buttons (radio-style)
• Hamburger menu with Map/About/Help/Settings + cache controls
• iOS PWA edge-to-edge display with safe area handling
• Semi-transparent UI elements with backdrop blur
• Sector model and API (prepared for future offline feature)
• Service worker cache versioning for updates

Add offline tile caching and fountain pin markers

• Service worker with IndexedDB caching for PMTiles range requests
• 50MB cache limit with LRU eviction for older tiles
• Cache status indicator showing online/offline state and cache size
• Water drop pin icons for fountains (blue=potable, red=not, gray=unknown)
• Zoom-based icon scaling for mobile visibility
• Official Protomaps basemap style (12k layer config)
• Graceful handling of missing sprite images

Switch from Leaflet to MapLibre with self-hosted PMTiles

• Add MapLibre GL JS and PMTiles protocol libraries
• Extract Camino Frances corridor from Protomaps (302MB, zoom 0-14)
• Upload to bunny.net CDN with range request support
• Custom basemap style optimized for pilgrims
• Route shown in Camino orange, fountains as colored circles
• Built-in geolocation control with heading indicator
• Tiles loaded on-demand via HTTP range requests (~200KB initial)

Add server management script and admin auth

• Create ./ultreia CLI for start/stop/restart/start-dev/status
• Add HTTP Basic Auth to admin controllers (env configurable)
• Document server commands and environment variables

Set up PWA foundation with manifest and service worker

• Enable PWA routes for manifest and service worker
• Configure manifest with Camino-themed colors and metadata
• Add service worker with network-first caching strategy
• Update layout with meta tags and SW registration
• Create scallop shell icon (SVG) - Camino symbol

App is now installable on mobile devices.

Add project documentation

• Development guidelines and common gotchas
• Architectural decisions, PWA strategy, offline-first approach

Add tri-state toggle component for potability field

• Create reusable tristate partial with yes/unknown/no states
• Add CSS component with color-coded segments (green/gray/red)
• Replace potable dropdown with toggle in fountain form
• Handle empty string to nil conversion in Fountain model
• Fix coordinate inputs alignment in form footer

Add admin CRUD for fountains with map picker

• Create FountainsController with full CRUD actions
• Build index view with potability badges and pagination
• Add show view with map preview and color-coded markers
• Implement form with Leaflet map picker and draggable marker
• Add geolocation button for "create here" functionality
• Support pasting Google Maps URLs or lat,lng coordinates
• Add virtual lat/lng attributes to Fountain model
• Include fountains in admin sidebar navigation

Add fountains with viewport-based map loading

Features:
- Fountain model with PostGIS point, potability (true/false/null)
- Imported 730 fountains from legacy Django database
- Viewport-based loading for routes and fountains (bbox filtering)
- Color-coded fountain markers (green/red/gray for potability)
- Debounced map updates (300ms) to prevent request spam
- Flicker-free layer swapping

API:
- GET /api/fountains?bbox=west,south,east,north
- GET /api/routes/:id/trackpoints?bbox=west,south,east,north