GaugeWatcher

Download on the App Store | View on GitHub

A native iOS and macOS app for monitoring river flow conditions in near-real-time, with an on-device AI assistant powered by Apple Intelligence.

Why I Built This

As a whitewater kayaker, I check river gauges constantly—sometimes obsessively. Flow rates determine whether a river is runnable, and conditions can change by the hour. Existing options were either web-only (frustrating on mobile) or iOS apps that hadn’t been updated in years.

I wanted an app that:

• Works offline (cell service is rare at put-ins)
• Aggregates data from multiple agencies (USGS, Environment Canada, Colorado DWR, LAWA)
• Feels native on both iPhone and Mac
• Could eventually predict conditions, not just report them

GaugeWatcher is my solution—and a playground for exploring Swift architecture patterns and Apple’s newest frameworks.

Technical Highlights

On-Device AI with Apple Intelligence

GaugeBot is a conversational interface powered by Apple’s Foundation Models framework. Users can ask questions like “What gauges are running in Colorado?” or “Show me my favorites” and get instant answers—all processed entirely on-device.

Capability	Example
Natural language search	”Find gauges on the Arkansas River”
Favorites access	”What are my saved stations?”
Contextual queries	”Which of my favorites are running high?”

The AI assistant uses tool calling to access the local database, meaning it can query actual gauge data rather than hallucinating responses. All processing happens on-device—no data leaves the user’s Mac or iPhone.

See the React Native Foundation Models lab project for how I extracted these learnings into a reusable library.

Multi-Platform Architecture

The app shares 90%+ of its code between iOS and macOS using The Composable Architecture (TCA):

┌─────────────────────────────────────────────────────────────────────────┐
│                              Applications                               │
├──────────────────────────────────┬──────────────────────────────────────┤
│          GaugeWatcher            │          GaugeWatcherMac             │
│          (iOS App)               │          (macOS App)                 │
└──────────────────────────────────┴──────────────────────────────────────┘
                                   │
                    ┌──────────────┴──────────────┐
                    │       SharedFeatures        │
                    │   (Cross-platform TCA)      │
                    └──────────────┬──────────────┘
                                   │
        ┌──────────────────────────┼──────────────────────────┐
        │                          │                          │
┌───────┴───────┐         ┌────────┴────────┐        ┌────────┴────────┐
│  GaugeSources │         │  GaugeDrivers   │        │  GaugeService   │
│  (Definitions)│         │  (API Clients)  │        │  (Data Layer)   │
└───────────────┘         └─────────────────┘        └────────┬────────┘
                                                              │
                                                     ┌────────┴────────┐
                                                     │   AppDatabase   │
                                                     │    (SQLite)     │
                                                     └─────────────────┘

Platform-specific code is minimal—primarily navigation patterns (tab bar vs. sidebar) and platform-appropriate UI conventions.

Offline-First Data Layer

River data is cached locally in SQLite with intelligent sync:

• Background refresh — data updates when the app is foregrounded
• Stale-while-revalidate — UI shows cached data immediately, then refreshes
• Selective sync — only fetch updates for favorited gauges to minimize bandwidth

Multi-Source Data Aggregation

Each government agency exposes data differently. I implemented a driver pattern that normalizes responses into a unified model:

Provider	Coverage	API Style
USGS	United States	REST/JSON
Environment Canada	BC, ON, QC	CSV over HTTP
Colorado DWR	Colorado	REST/JSON
LAWA	New Zealand	REST/JSON

Adding new data sources requires implementing a single protocol—the rest of the app is agnostic to where data originates.

Flow Forecasting

An experimental feature uses time-series forecasting to predict future river levels. See Flow Forecast for details on the Python/Prophet backend that powers this.

Technical Decisions

Decision	Rationale
TCA over vanilla SwiftUI	Testability, scalability, and explicit state management for a complex app
SQLite over SwiftData	More control over schema, better offline performance, proven at scale
Local packages over monolith	Clear boundaries between features; faster incremental builds
Apple Intelligence over cloud AI	Privacy-first; no API costs; works offline

Key Features

• Multi-source gauge data — USGS, Environment Canada, Colorado DWR, LAWA
• Interactive map — search and browse gauges with clustering for dense areas
• Historical charts — view trends over customizable time periods
• Favorites sync — iCloud sync across devices
• GaugeBot AI — natural language queries powered by on-device LLM

Learnings

• TCA at scale — the architecture shines for complex apps but has a learning curve; dependency injection and controlled side effects make testing dramatically easier
• Foundation Models framework — Apple’s on-device AI is capable but requires careful prompt engineering; tool calling enables useful domain-specific assistants
• Multi-platform SwiftUI — sharing code between iOS and macOS is viable but requires discipline around platform abstractions

Acknowledgments

• @ajbonich — Initial forecasting server implementation
• @ngottlieb — Canadian gauge data guidance