🔊 HushMap

Find your calm. Map the world by how it feels.

HushMap is an iOS app that helps people with sensory sensitivities — including autistic and neurodivergent users — discover how loud, crowded, and bright a place is before they arrive. It blends community reports with grounded AI predictions to make the physical world more navigable.

Features · Architecture · Quick Start · Examples · Roadmap · Contributing · Changelog

---

🌍 Why HushMap?

Maps tell you how to get somewhere. They don't tell you what it will feel like when you arrive — whether a café will be a gentle hum or an overwhelming roar at 1pm on a rainy Saturday.

For the millions of people with sensory processing differences, that gap is the difference between a good day and a hard one. HushMap fills it: every place on the map carries a noise / crowd / lighting profile, sourced from real community reports and grounded AI predictions, so you can plan around your own comfort.

Built for the Google Maps Platform Awards.

📸 Screenshots

Map & sensory pins	Venue prediction	Sensory profile

✨ Features

🗺️ Sensory mapping

• Community reports — log the noise, crowd, and lighting of any venue in seconds.
• Quick Update — frictionless one-tap sensory check-ins for places you're at right now.
• Live map — Google Maps with device-aware, clustered sensory pins that stay smooth even on older iPhones.

🤖 Grounded AI predictions

• Sensory forecasts — tap any place to get a noise / crowd / lighting prediction tuned for neurodivergent visitors, factoring in venue type, time, weather, and nearby reports.
• Web-grounded facts — an on-demand "interesting fact" for a venue, sourced live from the web (not hallucinated) with citations stripped for clean reading.
• Algorithmic fallback — if AI is unavailable, a transparent rule-based model keeps predictions working.

🧠 Personal sensory profile

• Learns your comfort — an on-device model adapts to your tolerances from your reports using comfort-weighted exponential moving averages.
• Smart notifications — proactive heads-up when you're near a place likely to be uncomfortable for you.
• Real-time noise meter — measure ambient dB with the mic and see it mapped to a sensory scale.

🔒 Privacy & accessibility first

• Google & Apple Sign-In, plus a fully-featured anonymous mode.
• GDPR/CCPA-compliant, one-tap account & data deletion.
• Full VoiceOver support, Dynamic Type, and a high-contrast mode.
• Apple Watch companion.

🏗️ Architecture

HushMap is a SwiftUI + SwiftData app backed by a thin, secure serverless layer. The OpenAI API key never ships in the app — all AI calls are proxied through Firebase Cloud Functions, gated by App Check.

flowchart TD
    subgraph device["iOS App - SwiftUI + SwiftData"]
        V["Views<br/>(SwiftUI)"] --> VM["ViewModels<br/>(Published state)"]
        VM --> S["Service layer<br/>(MainActor singletons)"]
        S --> DB[("SwiftData<br/>local store")]
        S --> AC["App Check<br/>(App Attest)"]
    end

    subgraph cloud["Firebase"]
        CF["Cloud Functions<br/>predictSensory - interestingFact<br/>(App Check enforced)"]
        FS[("Firestore<br/>community reports")]
        SM["Secret Manager<br/>(OpenAI key)"]
    end

    subgraph google["Google Maps Platform"]
        GM["Maps SDK"]
        GP["Places API"]
    end

    OA["OpenAI<br/>gpt-4.1-mini + web search"]

    S -->|"App Check token"| CF
    CF --> SM
    CF -->|"grounded predictions & facts"| OA
    S <-->|"sync reports"| FS
    S --> GM
    S --> GP
    AC -.->|"attest"| CF

    classDef app fill:#1575F9,stroke:#0a3d8f,color:#fff
    classDef fb fill:#FFA000,stroke:#c67c00,color:#fff
    classDef ext fill:#34A853,stroke:#1e7e34,color:#fff
    class V,VM,S,DB,AC app
    class CF,FS,SM fb
    class GM,GP,OA ext

Loading

Layers:

• Presentation — SwiftUI views with @State / @StateObject, driven by @Published view-model state and SwiftData @Query.
• Services — 20+ @MainActor singletons (prediction, location, audio, auth, sync, profile learning…) that own all business logic and I/O.
• Data — SwiftData for the local store; Firestore for shared community reports.
• Serverless — TypeScript Cloud Functions proxy OpenAI so the key stays server-side; App Check ensures only the genuine app can call them.

📖 Full deep-dive: docs/ARCHITECTURE.md

⚡ Quick Start (60 seconds)

Prerequisites: Xcode 16+, an iOS 18+ simulator, and a Google Maps Platform key with the Maps SDK for iOS + Places API enabled.

# 1. Clone
git clone https://github.com/nickjlamb/HushMap.git
cd HushMap

# 2. Add your Google keys (OpenAI is server-side — no key needed locally)
cp HushMap/Config.xcconfig HushMap/Config-Local.xcconfig
#   → edit HushMap/Config-Local.xcconfig and paste your keys

# 3. Open & run
open HushMap.xcodeproj      # then press ⌘R

That's it — Swift Package Manager resolves dependencies on first open, and you're running.

Note on AI features: predictions and venue facts call the maintainer's App-Check-gated Cloud Functions, so a fork won't have access to them out of the box. To enable AI in your own fork, deploy the functions in functions/ to your Firebase project — see functions/DEPLOY.md. Everything else (the map, community reports, sensory profile) runs without them.

💡 Examples

Calling the sensory-prediction proxy (client)

The app never talks to OpenAI directly — it calls a callable Cloud Function, and Firebase attaches the App Check token automatically:

let result = try await functions.httpsCallable("predictSensory").call([
    "venueName": "King's Cross Station",
    "venueType": "Transport Hub",
    "dayOfWeek": "Monday",
    "timeOfDay": "8:30 AM",
    "weather": "Rainy",
])
// → SensoryPredictionResult(noiseLevel: "very loud",
//                           crowdLevel: "very crowded",
//                           lightingLevel: "bright",
//                           summary: "King's Cross at 8:30am on a rainy Monday…")

Structured output the model must return

Predictions use OpenAI Structured Outputs with a strict schema, so levels map 1:1 to the app's SensoryLevel and can never come back malformed:

{
  "noise_level":    "very loud",     // very quiet | quiet | moderate | noisy | very loud
  "crowd_level":    "very crowded",  // empty | light | moderate | busy | very crowded
  "lighting_level": "bright",        // dim | soft | moderate | bright | very bright
  "summary": "Peak-hour commuter hub — expect intense noise and dense crowds. Consider noise-cancelling headphones and off-peak timing."
}

Grounded, non-hallucinated facts

Venue facts are fetched with the model's live web search tool and return a NO_FACT sentinel when nothing verifiable exists — so an obscure local shop gets a real fact or none, never an invented one:

Ty Cycles, Chipping Norton  →  "Did you know? TY Cycles is a family-run business
                                in Chipping Norton offering bike sales, servicing,
                                and hire."   ✅ sourced, not fabricated

🗂️ Project structure

HushMap/
├── HushMap/                    # iOS app
│   ├── Views/                  # SwiftUI screens (map, prediction, profile, …)
│   ├── ViewModels/             # @Published presentation state
│   ├── Services/               # 20+ @MainActor singletons (business logic + I/O)
│   ├── Models/                 # SwiftData @Model types (Report, User, SensoryProfile…)
│   ├── Map/ · UI/ · Utilities/ # Map integration, components, helpers
│   └── PrivacyInfo.xcprivacy   # Apple privacy manifest
├── functions/                  # Firebase Cloud Functions (TypeScript) — OpenAI proxy
│   ├── src/                    # predictSensory · interestingFact
│   └── DEPLOY.md               # deploy + troubleshooting guide
├── HushMapWatch Watch App/     # watchOS companion
├── docs/                       # architecture & deep-dive docs
└── HushMap.xcodeproj

🧰 Tech stack

Area	Tech
UI	SwiftUI, Dynamic Type, VoiceOver, high-contrast mode
Data	SwiftData (local), Cloud Firestore (shared)
AI	OpenAI gpt-4.1-mini, Structured Outputs, web-search grounding
Maps	Google Maps SDK for iOS, Places API
Backend	Firebase Cloud Functions (TypeScript, Node 20), App Check, Secret Manager
Auth	Google Sign-In, Apple Sign-In, anonymous mode
Platform	iOS 18+, watchOS companion, Swift 5.9 / Xcode 16

🗺️ Roadmap

A few things on the horizon — see ROADMAP.md for the full picture:

• 🌐 Offline-first sensory data for low-connectivity areas
• 🧭 Sensory-aware routing ("take me the quiet way")
• 📊 Richer venue analytics from aggregated community data
• ♿ Expanded accessibility profiles beyond noise/crowd/lighting

🤝 Contributing

Contributions are very welcome — whether it's code, a bug report, or a sensory report from your corner of the world. Start with CONTRIBUTING.md.

📓 Changelog

All notable changes are documented in CHANGELOG.md, following Keep a Changelog and Semantic Versioning.

🔐 Privacy & Security

• The OpenAI API key never ships in the app — all AI calls route through App-Check-gated Cloud Functions.
• Google API keys live in a gitignored Config-Local.xcconfig.
• Apple privacy manifest (PrivacyInfo.xcprivacy) declares data use and required-reason APIs.
• One-tap account & data deletion; minimal data collection; GDPR/CCPA aligned.

📄 License

MIT © 2025 Nick Lamb.

🙏 Acknowledgments

• The neurodivergent community, whose lived experience shapes every design decision.
• Google Maps Platform — Maps SDK & Places API.
• Firebase — Firestore, Cloud Functions, App Check.
• OpenAI — grounded sensory predictions.

_{Built with care for people who feel the world a little more intensely.}