PawMap is an AI-powered, location-aware stray-animal rescue, foster, and adoption platform built for HackFusion 2026.
It helps citizens report stray animals, discover nearby rescue needs on a map, review AI-assisted animal observations, and support rescue, foster, and adoption workflows in one place.
Stray animals are often seen in public spaces but information about them is fragmented across local communities, NGOs, shelters, and social messaging apps. People rarely know whether an animal is already being cared for, whether it has urgent needs, whether a nearby volunteer can help, or whether it is available for adoption.
This creates delays, duplicate reports, and poor visibility into the animal's lifecycle after it is reported.
PawMap brings reporting, map discovery, AI-assisted profile generation, duplicate detection, rescue workflow coordination, and adoption matching into a single system.
The platform is designed around a transparent lifecycle:
Reported → Verified → Rescue/Foster → Medical Care → Adoption → Adopted
PawMap is not a standard pet marketplace. Its differentiator is a combination of:
- location-aware community reporting
- AI-assisted profile generation from animal photos
- duplicate detection for nearby incident reports
- rescue/foster/adoption coordination
- lifecycle tracking from report to resolution
- OpenStreetMap + Leaflet-based animal map
- citizen reporting flow with photo upload and location capture
- AI-assisted animal profile extraction with editable review before submission
- duplicate detection workflow for possible repeated reports
- rescue request flow for volunteers and NGOs
- foster and adoption coordination views
- role-based dashboards for citizens, volunteers, NGOs, and admins
- in-app notifications and lifecycle timeline tracking
- fictional Chennai demo data for local hackathon presentation
PawMap uses Google Gemini for AI-assisted visual observation when configured.
The AI can interpret a photo and suggest:
- species
- animal type
- age group
- color/pattern
- visible attributes
- possible visible concerns
- confidence score
Important safety guidance:
- The AI output is advisory only.
- It is never presented as a veterinary diagnosis.
- The UI clearly labels this as: "AI-assisted visual observation — not a veterinary diagnosis."
- If the model cannot determine a value reliably, the result is set to "Unknown" rather than guessed.
PawMap is structured as a lightweight product MVP with a clean split between frontend and backend.
- Frontend: React + Vite + TypeScript + Tailwind CSS
- Routing: React Router
- Maps: Leaflet + OpenStreetMap
- Backend: FastAPI + Pydantic + Uvicorn
- Authentication: Firebase-ready with local demo auth fallback
- AI: Google Gemini, with demo-mode fallback when unavailable
- Data: local demo-first dataset for hackathon readiness
- React
- Vite
- TypeScript
- Tailwind CSS
- React Router
- Lucide React
- Leaflet + React Leaflet
- FastAPI
- Pydantic
- Firebase Admin SDK (optional production integration)
- Google Gemini (optional production AI)
PawMap/
├── frontend/
│ ├── src/
│ ├── public/
│ ├── package.json
│ ├── vite.config.ts
│ ├── .env.example
│ └── README.md
├── backend/
│ ├── app/
│ ├── tests/
│ ├── requirements.txt
│ ├── .env.example
│ └── README.md
├── docs/
│ ├── architecture.md
│ ├── api.md
│ ├── demo.md
│ └── screenshots/
├── .env.example
├── .gitignore
├── README.md
├── LICENSE
└── .venv/
This project is intentionally designed to work for local HackFusion demos without requiring live Firebase or Gemini credentials.
Use this for app demos, local testing, and judging.
AI_DEMO_MODE=trueDATA_MODE=demo- Firebase credentials are optional
- Gemini API is optional
- The app continues to work with fictional demo data and clearly labeled AI results
If you want to connect real services later, provide real environment values:
- Firebase project config values for frontend
- Firebase Admin config values for backend
GEMINI_API_KEYfor live AI analysis- set
AI_DEMO_MODE=falsewhen using the real AI service
Important:
- Demo mode is the safe default.
- Do not commit real secrets to the repo.
- Never expose Firebase private keys or service-account JSON files.
Use the sample env files as templates. Keep placeholders only.
Root .env.example:
GEMINI_API_KEY=
AI_DEMO_MODE=true
DATA_MODE=demo
BACKEND_URL=http://localhost:8000
VITE_FIREBASE_API_KEY=
VITE_FIREBASE_AUTH_DOMAIN=
VITE_FIREBASE_PROJECT_ID=
VITE_FIREBASE_STORAGE_BUCKET=
VITE_FIREBASE_MESSAGING_SENDER_ID=
VITE_FIREBASE_APP_ID=
VITE_API_URL=http://localhost:8000Backend .env.example:
APP_NAME=PawMap API
BACKEND_URL=http://localhost:8000
ALLOWED_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
FIREBASE_PROJECT_ID=
FIREBASE_PRIVATE_KEY=
FIREBASE_CLIENT_EMAIL=
GEMINI_API_KEY=
AI_DEMO_MODE=true
DATA_MODE=demoFrom the project root:
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r backend/requirements.txtcd frontend
npm installcd backend
..\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reloadcd frontend
Set-ExecutionPolicy -Scope Process Bypass
$env:VITE_API_URL = "http://localhost:8000"
npm run dev -- --host 127.0.0.1Open the app at:
- frontend: http://127.0.0.1:5173
- backend: http://127.0.0.1:8000
- Open the landing page.
- Explore nearby animals on the map.
- Open an animal profile.
- Log in with a demo account.
- Submit a new animal report.
- Upload or select an image.
- Run AI analysis.
- Review and edit AI-generated information.
- Submit the report.
- Confirm the new animal appears in listings and on the map.
- Review duplicate detection behavior.
- Open the adopter flow to see AI-assisted compatibility scoring.
- Submit a foster or rescue request.
- Visit the dashboard to review notifications and lifecycle updates.
asha@example.com/demo123admin@example.com/demo123
These are demo credentials for local use only.
The repository is prepared to display application screenshots in the docs/screenshots/ folder.
Add the following images there as the project evolves:
- landing-page.png
- map-view.png
- animal-profile.png
- report-form.png
- dashboard.png
- adoption-match.png
A placeholder documentation file is included in docs/screenshots/ to make the folder ready for screenshots.
- production Firebase Firestore + Storage integration
- real volunteer verification workflows
- stronger image-similarity matching
- richer adoption compatibility scoring
- SMS/WhatsApp notifications
- broader admin and reporting analytics
This is an MVP built for a HackFusion demo and local validation.
- it is not a replacement for a full production animal welfare platform
- AI observations are advisory and not clinical diagnosis
- map and listing data are demo-first for local use
- real Firebase/Gemini integration is optional and must be configured separately
PawMap is designed to encourage responsible animal care, not unsafe handling.
If an animal appears injured, trapped, or aggressive, users should contact a qualified veterinarian or a local rescue organization instead of attempting unsafe handling.
AI-generated animal observations are not a veterinary diagnosis. Any AI-powered profile should be reviewed by a human before action is taken.