Nearby Nook

A calm, practical way to discover the useful places around you.

Nearby Nook is a guest-first local discovery app for Philippine neighborhoods. Search a city, barangay, landmark, or address to explore cafés, restaurants, parks, libraries, coworking spaces, and more—using open, community-maintained OpenStreetMap data.

Explore real nearby places on an interactive, clustered map. Map data © OpenStreetMap contributors.

Why Nearby Nook?

• Search the way people think. Find places by city, neighborhood, landmark, or address—or use browser location with permission.
• Make sense of what is nearby. Set a 1–10 km radius, browse meaningful categories, sort results, and move between map-and-card, map-only, and list views.
• Keep a lightweight plan. Save places and build a device-local visit plan without creating an account.
• Be clear about the data. Fields are shown only when OpenStreetMap provides them; unavailable details are called out rather than invented.

Product highlights

Explore places	Decide with context
Clustered Leaflet pins stay connected to result cards, making dense neighborhoods easier to scan.	A responsive desktop drawer and mobile sheet show address, available hours, directions, services, and data-source context.

Features

• Search a location or use browser geolocation
• Discover cafés, restaurants, gyms, libraries, coworking spaces, parks, museums, and historic places
• Combine category filters, sort results, and search within a visible 1–10 km radius
• Explore map clusters, cards, and accessible place details
• Save places, assemble a local visit plan, copy addresses, and open walking directions
• Share a selected place with a URL that preserves the search context
• Use loading states, error recovery, keyboard focus, and reduced-motion support across the experience

Built with

Area	Technology
Interface	React, Vite, plain CSS design tokens
Maps	Leaflet, React Leaflet, React Leaflet Cluster
Open data	OpenStreetMap, Nominatim, Overpass API
Local API	Node.js validation, caching, throttling, provider failover, and health reporting
Time & storage	opening_hours, browser localStorage
Future-ready persistence	PostgreSQL migration foundation via pg

Architecture

flowchart LR
  Browser[React browser app] --> API[Same-origin Node API]
  API --> Cache[Cache and rate limiter]
  API --> Nominatim[OpenStreetMap Nominatim]
  API --> Overpass[Overpass API]
  API -. optional .-> Database[(PostgreSQL)]

Loading

• src/main.jsx coordinates search, selection, responsive views, URL state, and local persistence.
• src/services/osm.js is the browser client for the versioned Nearby Nook API.
• server/ owns validation, provider access, caching, request limits, and production asset delivery.
• src/domain.js, src/filters.js, src/openingHours.js, src/storage.js, and src/urlState.js keep data normalization and UI behavior modular.
• db/migrations/0001_foundation.sql provides an additive PostgreSQL foundation for future account synchronization.

For deeper implementation notes, see the architecture overview and operations runbook.

Run locally

Requirements: a current Node.js LTS release and npm.

git clone https://github.com/ailevated-randy-alonzo/nearby-nook.git
cd nearby-nook
npm install
npm run dev

Open http://localhost:5173. The development command starts both the Vite app and its local API.

To override local settings, copy .env.example to .env. DATABASE_URL is optional until synchronized accounts are enabled.

Quality checks

npm run check

This runs the Vitest suite and produces a production build. To run that build through the Node server:

npm run build
npm start

The API health check is available at /api/v1/health while the production server is running. Apply the optional database foundation with npm run db:migrate after setting DATABASE_URL.

Data and privacy

Nearby Nook displays place fields only when they are available from OpenStreetMap. Ratings, menus, fares, live routes, reviews, crowd levels, historical notes, and other unverified details intentionally show an availability fallback until a verified provider is connected.

Saved places and visit plans stay on the current device. If public Overpass providers are temporarily unavailable during local development, the app enters a clearly labeled Demo data mode with sample records—it never silently presents sample records as live businesses.

Production notes

Before a public deployment, set OSM_CONTACT_EMAIL and an identifying OSM_USER_AGENT, then review the Nominatim usage policy, Overpass guidance, and tile usage policy. The included cache and rate limiter are process-local; multi-instance deployments should use shared managed infrastructure.

Next up

• Verified photos, ratings, reviews, menus, and amenity contributions
• Routing, public transit, fares, and travel-time providers
• Account-backed saved places, itineraries, and community updates

---

Built with React, Leaflet, and the open geospatial community. Contributions and ideas are welcome.