Sanket — सङ्केत

Real-time road hazard signals for Nepal.

Sanket is a citizen-reporting platform for road hazards in Nepal — landslides, floods, potholes, and similar incidents that block or endanger a route. Citizens report through the mobile app; local authorities review and verify through the web dashboard.

---

Architecture

Mobile App (Android APK)          Web App (Admin & Authority)
  React + Capacitor                 React + Vite
  Camera | Geolocation              React Router v6
        │                                 │
        └──────────── Firebase ───────────┘
                   Firestore (data)
                   Firebase Storage (photos)
                   Firebase Auth (users)
                   Cloud Functions (logic)

• Mobile app — report road hazards, view nearby incidents, confirm existing reports.
• Authority web app — district-scoped dashboard to verify or reject submitted reports.
• Admin web app — full system view, analytics, override any decision.

---

Setup

Prerequisites

• Node.js 18+
• A Firebase project (the existing sanket-87ef4 project is already configured)

1. Clone & install

git clone <repo-url>
cd Sanket
npm install

2. Environment variables

cp .env.example .env
# Fill in your Firebase config values from:
# Firebase Console → Project Settings → General → Your apps → Web app

⚠️ Key rotation required: The Firebase API key was previously committed to the repository. Rotate it now: Firebase Console → Project Settings → General → Web API Key → Regenerate. Put the new key in .env only — never commit .env.

3. Run the web app (dev)

npm run dev
# Opens at http://localhost:5173

4. Seed dummy data

# 1. Download serviceAccountKey.json from:
#    Firebase Console → Project Settings → Service accounts → Generate new private key
# 2. Place it in the project root (it's gitignored)
# 3. Install firebase-admin:
npm install firebase-admin
# 4. Run the seed script:
node scripts/seed.mjs

5. Deploy Firestore & Storage rules

npm install -g firebase-tools
firebase login
firebase deploy --only firestore:rules,storage:rules

The repository now includes firebase.json and firestore.indexes.json, so that command deploys the workflow security rules and the indexes required by the live reporter, district, and map feeds. Deploy the full backend after the functions are built with:

firebase deploy

6. Deploy Cloud Functions

cd functions
npm install
npm run build
cd ..
firebase deploy --only functions

---

Test Credentials

⚠️ These are for demo/testing only. Rotate all passwords before any real deployment.

Role	Email	Password	Scope
Admin	admin@sanket.np	Admin@1234	All districts
Authority	authority.ktm@sanket.np	Auth@1234	Kathmandu, Lalitpur, Bhaktapur
Authority	authority.pkr@sanket.np	Auth@1234	Kaski, Tanahu
Authority	authority.chit@sanket.np	Auth@1234	Chitwan, Makwanpur
User	user1@sanket.np	User@1234	—
User	user2@sanket.np	User@1234	—

---

Mobile APK Build (Android)

No local Android Studio required. The APK is built via GitHub Actions.

Steps to get an APK

1. Push to the main branch (or go to GitHub → Actions → "Build Android APK" → Run workflow).
2. Wait for the workflow to complete (~5–8 minutes).
3. Download sanket-debug.apk from the workflow run's Artifacts section.
4. Transfer to an Android device and install (enable "Install from unknown sources" in settings).

Required GitHub Actions secrets

Add these in GitHub → Settings → Secrets and variables → Actions:

Secret	Value
VITE_FIREBASE_API_KEY	Your Firebase API key
VITE_FIREBASE_AUTH_DOMAIN	e.g. sanket-87ef4.firebaseapp.com
VITE_FIREBASE_PROJECT_ID	sanket-87ef4
VITE_FIREBASE_STORAGE_BUCKET	sanket-87ef4.firebasestorage.app
VITE_FIREBASE_MESSAGING_SENDER_ID	Your sender ID
VITE_FIREBASE_APP_ID	Your app ID

Capacitor setup (one-time, if android/ folder is missing)

npm install @capacitor/core @capacitor/cli @capacitor/android
npm install @capacitor/camera @capacitor/geolocation @capacitor/preferences
npx cap init "Sanket" "np.sanket.app" --web-dir dist
npx cap add android
npm run build
npx cap sync android

---

Feature Flags

Variable	Default	Description
VITE_AI_SCREENING_ENABLED	false	Enable AI image screening in admin review (requires Google Cloud Vision setup — see design.md)

---

Project Structure

src/
  components/      Shared UI components (AddressSearchInput, IncidentsMap, etc.)
  lib/             Services (firebase, auth, incidents, storage, geo, districts, offlineQueue)
  mobile/          Mobile app screens (MobileApp, ViewTab, ContributeTab, ProfileTab)
  pages/           Web app pages (Landing, AdminDashboard, AuthorityDashboard, auth/)
  types/           TypeScript types (Report, Confirmation, AppUser, etc.)
functions/         Firebase Cloud Functions (TypeScript)
scripts/           Seed script
firestore.rules    Firestore security rules
storage.rules      Storage security rules
.github/workflows/ APK build workflow