TripSense

TripSense is an Expo/React Native trip app backed by a real Node.js API. The app uses live device location, real OpenStreetMap data, and local SQLite persistence. It does not require a paid API, hosted database, AI subscription, or SMS provider.

What works

• Route Discovery: geocodes the destination, calculates a driving route, and finds real food, parks, lakes, cafes, or fuel stops near that route.
• Safety Tracker: persists contacts, location check-ins, trip records, daily summaries, and share audit events per app installation.
• Tourist Mode: builds a multi-day plan from real nearby OpenStreetMap attractions and food places.
• Sharing: opens the phone's native share sheet. The user can choose SMS, WhatsApp, email, or another installed app without a paid server-side messaging provider.
• NATPAC planning dashboard: publishes consented, anonymised trip aggregates as an OD heatmap, mode share, and peak-hour flow profile at /natpac/.
• Trip Expenses: records categorized expenses, monthly totals, and receipt-assisted entry using local Tesseract OCR.
• Indian language accessibility: includes offline English, Hindi, and Malayalam UI translations, with additional languages available through a configured BHASHINI/National Language Translation Mission pipeline.

Requirements

• Node.js 22.13 or newer (the backend uses Node's built-in SQLite module)
• npm
• Expo Go, an iOS simulator, an Android emulator, or a web browser

First-time setup

Install both dependency sets:

npm install
npm install --prefix server

Create your local environment files:

cp .env.example .env
cp server/.env.example server/.env

In server/.env, replace the example OSM_USER_AGENT contact email. Public OpenStreetMap services require an identifiable user agent. Keep CLIENT_ORIGIN set to the exact Expo web origin. Do not use * when the API is reachable from the internet.

For BHASHINI languages beyond the offline core, add BHASHINI_USER_ID, BHASHINI_API_KEY, and BHASHINI_PIPELINE_ID from your BHASHINI profile to server/.env. The language screen reports whether that connection is ready.

Start the API in one terminal:

npm run server:dev

Start Expo in another:

npm start

Open http://localhost:4000/natpac/ for the NATPAC dashboard. Set NATPAC_DASHBOARD_TOKEN in server/.env before sharing it outside local development; the dashboard asks for that token when it loads the aggregate feed.

The default API address is http://localhost:4000 on iOS/web and http://10.0.2.2:4000 on the Android emulator. A physical phone cannot use your computer's localhost; set EXPO_PUBLIC_API_URL in .env to the computer's LAN address, such as http://192.168.1.10:4000, then restart Expo.

Verification

npm run server:test
npx expo export --platform web

The backend tests cover health, validation, route mapping, itinerary generation, contact isolation, expenses, receipt parsing, BHASHINI translation, check-ins, trip summaries, sharing, and NATPAC privacy thresholds.

Docker option

The API can also run locally or on your own machine with persistent SQLite storage:

docker compose up --build

No cloud account is required. Docker binds the API to 127.0.0.1 by default. If a reverse proxy runs on another host interface, set API_BIND_ADDRESS deliberately and protect the API with HTTPS and a firewall.

Project structure

src/
  api/          Expo API client and feature contracts
  services/     Device services such as foreground location
  screens/      App screens
server/
  src/app.js          HTTP routes, validation, security, errors
  src/services/       Feature business logic
  src/providers/      Replaceable map-data adapter
  src/repositories/   SQLite persistence
  public/natpac/      NATPAC aggregate dashboard
  test/               Backend integration tests
docs/
  BACKEND_ARCHITECTURE.md

Honest production limits

The default Nominatim, OSRM, and Overpass URLs are community-operated public services. They are excellent for development and small demos but are rate-limited and provide no uptime guarantee. For a larger public launch, self-host those same open-source services or replace the provider adapter with another provider.

Safety currently supports explicit location check-ins and a complete trip-recording API. Continuous background trip detection is not enabled because it needs a custom development build, background-location permissions, clear privacy controls, and battery testing. Anonymous device IDs provide data separation for development, not full user authentication. See the architecture document for the upgrade path.

NATPAC data sharing is opt-in per recorded trip. Exact coordinates are converted immediately to coarse grid zones and are never written to the planning table. Device IDs, place labels, and sub-threshold groups are excluded from the dashboard feed.

Receipt photos are processed in memory and are not stored by TripSense. OCR only prefills the expense form; the user can correct the merchant, amount, date, and category before saving. Tesseract currently uses bundled English receipt text data.