From 35f76b8823d816c14548cc1611dccb1e4c8aa164 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eren=20Kaan=20=C3=87AKIR?= Date: Mon, 12 Oct 2026 17:48:56 +0300 Subject: [PATCH 1/2] docs: add README Co-Authored-By: Claude Opus 5.5 --- README.md | 140 ++++++++++++++++++ API_SETUP.md => docs/API_SETUP.md | 0 .../AUTHENTICATION_SETUP.md | 0 BLUETOOTH_SETUP.md => docs/BLUETOOTH_SETUP.md | 0 CLEANUP_SUMMARY.md => docs/CLEANUP_SUMMARY.md | 0 .../GIT_COMMIT_GUIDE.md | 0 .../MIXED_USB_WIRELESS_SETUP.md | 0 .../ONE_CABLE_MULTIPLE_DEVICES.md | 0 .../QUICK_START_MULTIPLE_DEVICES.md | 0 QUICK_TEST.md => docs/QUICK_TEST.md | 0 README_TESTS.md => docs/README_TESTS.md | 0 .../TESTING_MULTIPLE_ANDROID_DEVICES.md | 0 .../TEST_FINAL_STATUS.md | 0 TEST_FIX.md => docs/TEST_FIX.md | 0 TEST_STATUS.md => docs/TEST_STATUS.md | 0 .../TEST_TROUBLESHOOTING.md | 0 16 files changed, 140 insertions(+) create mode 100644 README.md rename API_SETUP.md => docs/API_SETUP.md (100%) rename AUTHENTICATION_SETUP.md => docs/AUTHENTICATION_SETUP.md (100%) rename BLUETOOTH_SETUP.md => docs/BLUETOOTH_SETUP.md (100%) rename CLEANUP_SUMMARY.md => docs/CLEANUP_SUMMARY.md (100%) rename GIT_COMMIT_GUIDE.md => docs/GIT_COMMIT_GUIDE.md (100%) rename MIXED_USB_WIRELESS_SETUP.md => docs/MIXED_USB_WIRELESS_SETUP.md (100%) rename ONE_CABLE_MULTIPLE_DEVICES.md => docs/ONE_CABLE_MULTIPLE_DEVICES.md (100%) rename QUICK_START_MULTIPLE_DEVICES.md => docs/QUICK_START_MULTIPLE_DEVICES.md (100%) rename QUICK_TEST.md => docs/QUICK_TEST.md (100%) rename README_TESTS.md => docs/README_TESTS.md (100%) rename TESTING_MULTIPLE_ANDROID_DEVICES.md => docs/TESTING_MULTIPLE_ANDROID_DEVICES.md (100%) rename TEST_FINAL_STATUS.md => docs/TEST_FINAL_STATUS.md (100%) rename TEST_FIX.md => docs/TEST_FIX.md (100%) rename TEST_STATUS.md => docs/TEST_STATUS.md (100%) rename TEST_TROUBLESHOOTING.md => docs/TEST_TROUBLESHOOTING.md (100%) diff --git a/README.md b/README.md new file mode 100644 index 0000000..212dd5d --- /dev/null +++ b/README.md @@ -0,0 +1,140 @@ +# QuakePath + +An Expo / React Native app for earthquake emergencies. You can raise SOS alerts on a live Mapbox map, get a route to a safe assembly point, and keep messaging nearby phones over a Bluetooth Low Energy (BLE) mesh when the cellular network is down. + +Project website: **https://kaancakr.github.io/quake-path/** + +## Features + +- **Live SOS map.** The dashboard shows your position on a Mapbox map, which switches between day and night styles with the app theme. **Send SOS** saves an emergency with your GPS coordinates to Cloud Firestore. Every emergency appears on everyone's map as a marker in real time. Opening one shows a live message thread for that alert and draws a line from you to it. +- **Routes to safe assembly points.** A swipe-up sheet lists safe assembly points that you can search. For now this is a fixed list of six sites in Çankaya, Ankara. Pick one and the app draws a driving route to it using the Mapbox Directions API. +- **Offline BLE mesh (Mesh screen).** Phones running QuakePath find each other through a custom BLE GATT service, connect automatically and exchange JSON messages. Each message has an ID, so a phone ignores copies it has already seen. It also has a hop limit (TTL 5), and phones pass it on to their other connected peers, so a message can reach phones outside direct Bluetooth range. The screen shows: + - nearby devices with signal strength (RSSI) and the peers you are connected to + - a chat that vibrates and shows a local notification when a message arrives + - an emergency button that sends your location to all connected peers and also records the alert in Firestore +- **Location sync with mesh fallback.** Every 30 minutes, and whenever an emergency is sent from the Mesh screen, the app posts the device location to the backend API. If the API can't be reached, the location goes out over the mesh marked "needs forwarding". A peer that does have a connection uploads it. Failed uploads are queued and retried. +- **Civilian and rescue-team roles.** Users sign in to Firebase Authentication with email and password and choose a role at sign-up. The role is stored in Firestore. Rescue-team accounts see the latest synced civilian locations on the map, refreshed every 5 minutes. +- **Emergency screen.** Ready-made Turkish messages ("I need help", "I'm trapped under debris", "I'm safe", "I need medical help") with your coordinates added. +- **Help screen.** Tap-to-call Turkish emergency numbers (AFAD 122, police, ambulance, fire brigade, gendarmerie, Alo Deprem 186), an earthquake-kit checklist, and links to AFAD's website and earthquake map. +- **Notifications and theme.** On launch, the app asks for notification permission and registers for an Expo push token. Your light/dark theme choice is saved on the device. + +### Current limitations + +- **No earthquake data feed.** The app doesn't download earthquake events from any source. The Help screen links to AFAD instead. +- **Full mesh works on Android only.** The BLE advertiser and GATT server, which let a phone be discovered and receive messages, are native Kotlin modules. iOS builds can scan for and connect to other phones, but they can't advertise or receive. +- **Emergency-screen messages aren't sent yet.** Tapping a ready-made message only shows a confirmation. Sending it over the mesh isn't connected yet. +- **Mixed language.** The interface is partly Turkish and partly English. +- **Unused experiment.** `hooks/MeshRouter.ts`, `hooks/useNearbyMesh.ts` and `NearbyMeshModule.kt` are an experimental transport using Google Nearby Connections. The app doesn't register or use them. + +## Tech stack + +| Area | Tools | +| --- | --- | +| App | Expo SDK 52 (development build), React Native 0.76 with the New Architecture, TypeScript, Expo Router (drawer), Reanimated, Gesture Handler | +| Maps | `@rnmapbox/maps`, Mapbox Directions API, Expo Location | +| Mesh | `react-native-ble-plx` to scan and connect, plus custom Kotlin modules for the BLE advertiser and GATT server | +| Data | Firebase Authentication, Cloud Firestore, AsyncStorage, Expo Notifications | +| Backend (`server/`) | Node.js, Express, PostgreSQL (`pg`), Socket.IO | +| Testing | Jest (`jest-expo`), React Native Testing Library, GitHub Actions | + +## Project structure + +``` +app/ Expo Router screens + login.tsx Sign in / sign up with role selection + (drawer)/dashboard Map, SOS alerts, safe assembly points, rescue-team view + (drawer)/mesh BLE mesh: discovery, chat, emergency broadcast + (drawer)/emergency Ready-made emergency messages + (drawer)/help Emergency numbers, kit checklist, AFAD links + (drawer)/settings Account and preferences +hooks/ useMeshNetwork (BLE mesh), useLocationSync, useInternetConnectivity +context/ Firebase auth and theme providers +utils/ Firestore emergency helpers, geo helpers, native advertiser bridge +api/ Typed client for the backend location API +server/ Express + PostgreSQL backend (separate npm package) +android/ Native Android project, including the Kotlin mesh modules +ios/ Native iOS project +scripts/ adb helpers for installing on several Android devices at once +docs/ Setup guides and development notes +``` + +**`api/` and `server/`.** `server/` is a small Express API. It stores device locations in a PostgreSQL `user_locations` table, which it creates on startup. Its endpoints are: + +- `POST /api/locations` +- `GET /api/locations/device/:deviceId` +- `GET /api/locations/recent` +- `GET /api/locations/civilians` +- `GET /api/devices`, which the app also calls to check whether it has a connection + +`api/` is the app's typed client for these endpoints. The server also has a Socket.IO relay and an `/admin` page that lists connected devices. Both are left over from an earlier design where the mesh ran through the server; the current app doesn't use Socket.IO. + +## Getting started + +### Prerequisites + +- Node.js. CI uses Node 18. +- Android Studio with the Android SDK, and/or Xcode for iOS. +- Two or more physical Android phones to try the mesh. BLE doesn't work in emulators. + +The app uses native modules, so it runs as an Expo development build. It doesn't work in Expo Go. + +### App + +```bash +npm install +npm run android # expo run:android - build and install a dev build +npm run ios # expo run:ios +npm start # expo start - start Metro for an installed dev build +``` + +To install on several Android devices at once, run `./scripts/install-all-devices.sh`. See the multi-device guides below. + +### Tests + +```bash +npm test # run the Jest suite +npm run test:coverage # with coverage report +npm run test:simple # lightweight config (jest.config.simple.js) +``` + +GitHub Actions (`.github/workflows/test.yml`) runs `npm run test:ci` on every push and pull request to `master`/`main`. + +### Backend + +```bash +cd server +npm install +npm run dev # nodemon; or: npm start +``` + +The backend needs a running PostgreSQL database. + +### Configuration + +The repo contains no example env files. Everything below comes from the code. + +**App** + +- `EXPO_PUBLIC_API_URL` sets the backend base URL. `API_URL` is also read. Without either, debug builds use `http://10.0.2.2:3000` on the Android emulator and `http://localhost:3000` on the iOS simulator. +- `FirebaseConfig.ts` (repo root) is imported as `@/FirebaseConfig` but isn't committed. Create it and export an initialized Firebase `auth` and Firestore `db`. In the Firebase console, turn on Email/Password sign-in and Firestore. +- **Mapbox:** add your public access token where `Mapbox.setAccessToken` is called in `app/(drawer)/dashboard/index.tsx`. Add your downloads token as `RNMapboxMapsDownloadToken` in `app.json`. Both are placeholders in the repo. +- `expo.extra.eas.projectId` in `app.json` is needed for the Expo push token. Without it the app doesn't crash, but it gets no token. + +**Server** (`server/.env`, loaded with dotenv) + +- `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`, `PORT` + +## Documentation + +- [API and database setup](docs/API_SETUP.md) +- [Firebase authentication and roles](docs/AUTHENTICATION_SETUP.md) +- [Bluetooth mesh setup](docs/BLUETOOTH_SETUP.md) +- [Testing on multiple Android devices](docs/TESTING_MULTIPLE_ANDROID_DEVICES.md) +- Installing on several devices: [quick start](docs/QUICK_START_MULTIPLE_DEVICES.md), [one cable, many devices](docs/ONE_CABLE_MULTIPLE_DEVICES.md), [USB + wireless ADB](docs/MIXED_USB_WIRELESS_SETUP.md) +- [Test guide](docs/README_TESTS.md) (Turkish) +- [Frontend API client](api/README.md) and [backend server](server/README.md) + +## Links + +- Project website: https://kaancakr.github.io/quake-path/ +- Website source: https://github.com/kaancakr/quake-path diff --git a/API_SETUP.md b/docs/API_SETUP.md similarity index 100% rename from API_SETUP.md rename to docs/API_SETUP.md diff --git a/AUTHENTICATION_SETUP.md b/docs/AUTHENTICATION_SETUP.md similarity index 100% rename from AUTHENTICATION_SETUP.md rename to docs/AUTHENTICATION_SETUP.md diff --git a/BLUETOOTH_SETUP.md b/docs/BLUETOOTH_SETUP.md similarity index 100% rename from BLUETOOTH_SETUP.md rename to docs/BLUETOOTH_SETUP.md diff --git a/CLEANUP_SUMMARY.md b/docs/CLEANUP_SUMMARY.md similarity index 100% rename from CLEANUP_SUMMARY.md rename to docs/CLEANUP_SUMMARY.md diff --git a/GIT_COMMIT_GUIDE.md b/docs/GIT_COMMIT_GUIDE.md similarity index 100% rename from GIT_COMMIT_GUIDE.md rename to docs/GIT_COMMIT_GUIDE.md diff --git a/MIXED_USB_WIRELESS_SETUP.md b/docs/MIXED_USB_WIRELESS_SETUP.md similarity index 100% rename from MIXED_USB_WIRELESS_SETUP.md rename to docs/MIXED_USB_WIRELESS_SETUP.md diff --git a/ONE_CABLE_MULTIPLE_DEVICES.md b/docs/ONE_CABLE_MULTIPLE_DEVICES.md similarity index 100% rename from ONE_CABLE_MULTIPLE_DEVICES.md rename to docs/ONE_CABLE_MULTIPLE_DEVICES.md diff --git a/QUICK_START_MULTIPLE_DEVICES.md b/docs/QUICK_START_MULTIPLE_DEVICES.md similarity index 100% rename from QUICK_START_MULTIPLE_DEVICES.md rename to docs/QUICK_START_MULTIPLE_DEVICES.md diff --git a/QUICK_TEST.md b/docs/QUICK_TEST.md similarity index 100% rename from QUICK_TEST.md rename to docs/QUICK_TEST.md diff --git a/README_TESTS.md b/docs/README_TESTS.md similarity index 100% rename from README_TESTS.md rename to docs/README_TESTS.md diff --git a/TESTING_MULTIPLE_ANDROID_DEVICES.md b/docs/TESTING_MULTIPLE_ANDROID_DEVICES.md similarity index 100% rename from TESTING_MULTIPLE_ANDROID_DEVICES.md rename to docs/TESTING_MULTIPLE_ANDROID_DEVICES.md diff --git a/TEST_FINAL_STATUS.md b/docs/TEST_FINAL_STATUS.md similarity index 100% rename from TEST_FINAL_STATUS.md rename to docs/TEST_FINAL_STATUS.md diff --git a/TEST_FIX.md b/docs/TEST_FIX.md similarity index 100% rename from TEST_FIX.md rename to docs/TEST_FIX.md diff --git a/TEST_STATUS.md b/docs/TEST_STATUS.md similarity index 100% rename from TEST_STATUS.md rename to docs/TEST_STATUS.md diff --git a/TEST_TROUBLESHOOTING.md b/docs/TEST_TROUBLESHOOTING.md similarity index 100% rename from TEST_TROUBLESHOOTING.md rename to docs/TEST_TROUBLESHOOTING.md From 71dc35986ec58c5c49dccb279f4776730d4d9f93 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eren=20Kaan=20=C3=87AKIR?= Date: Mon, 12 Oct 2026 17:48:56 +0300 Subject: [PATCH 2/2] docs: move setup and test notes into docs/ Updates the paths in scripts/ and docs/GIT_COMMIT_GUIDE.md that pointed to the old locations. Co-Authored-By: Claude Opus 5.5 --- docs/GIT_COMMIT_GUIDE.md | 14 +++++++------- scripts/install-all-devices.sh | 2 +- scripts/quick-mixed-setup.sh | 2 +- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/GIT_COMMIT_GUIDE.md b/docs/GIT_COMMIT_GUIDE.md index fc26f2c..d8cc4b6 100644 --- a/docs/GIT_COMMIT_GUIDE.md +++ b/docs/GIT_COMMIT_GUIDE.md @@ -43,13 +43,13 @@ package-lock.json #### Test Dokümantasyonları ``` -TEST_FINAL_STATUS.md -TEST_FIX.md -TEST_STATUS.md -TEST_TROUBLESHOOTING.md -README_TESTS.md -QUICK_TEST.md -CLEANUP_SUMMARY.md +docs/TEST_FINAL_STATUS.md +docs/TEST_FIX.md +docs/TEST_STATUS.md +docs/TEST_TROUBLESHOOTING.md +docs/README_TESTS.md +docs/QUICK_TEST.md +docs/CLEANUP_SUMMARY.md ``` **Not:** Bu dosyalar yardımcı dokümantasyon, commit etmek zorunda değilsiniz diff --git a/scripts/install-all-devices.sh b/scripts/install-all-devices.sh index b1e0103..4a3866c 100755 --- a/scripts/install-all-devices.sh +++ b/scripts/install-all-devices.sh @@ -94,4 +94,4 @@ echo "" echo "💡 Tips:" echo " - Use a USB hub to connect multiple devices with one cable" echo " - Or set up wireless ADB for cable-free installation" -echo " - See ONE_CABLE_MULTIPLE_DEVICES.md for detailed instructions" +echo " - See docs/ONE_CABLE_MULTIPLE_DEVICES.md for detailed instructions" diff --git a/scripts/quick-mixed-setup.sh b/scripts/quick-mixed-setup.sh index a894630..bbcb48e 100755 --- a/scripts/quick-mixed-setup.sh +++ b/scripts/quick-mixed-setup.sh @@ -44,7 +44,7 @@ if [ "$USB_COUNT" -eq 0 ] && [ "$WIRELESS_COUNT" -eq 0 ]; then echo " - Run: adb pair :" echo " - Run: adb connect :" echo "" - echo "See MIXED_USB_WIRELESS_SETUP.md for detailed instructions" + echo "See docs/MIXED_USB_WIRELESS_SETUP.md for detailed instructions" exit 1 fi