Skip to content
kspraveen-07Public

About

AI-powered stray-animal rescue, foster, and adoption platform.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

PawMap

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.

Problem

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.

Solution

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

Key innovation

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

Features

  • 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

AI capabilities

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.

Architecture

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

Tech stack

  • 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)

Project structure

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/

Demo mode vs production configuration

This project is intentionally designed to work for local HackFusion demos without requiring live Firebase or Gemini credentials.

Demo mode (default for local runs)

Use this for app demos, local testing, and judging.

  • AI_DEMO_MODE=true
  • DATA_MODE=demo
  • Firebase credentials are optional
  • Gemini API is optional
  • The app continues to work with fictional demo data and clearly labeled AI results

Production configuration

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_KEY for live AI analysis
  • set AI_DEMO_MODE=false when 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.

Environment variables

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:8000

Backend .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=demo

Quick start

1) Create the Python environment

From 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.txt

2) Install frontend dependencies

cd frontend
npm install

3) Start the backend

cd backend
..\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload

4) Start the frontend

cd frontend
Set-ExecutionPolicy -Scope Process Bypass
$env:VITE_API_URL = "http://localhost:8000"
npm run dev -- --host 127.0.0.1

Open the app at:

Demo instructions

  1. Open the landing page.
  2. Explore nearby animals on the map.
  3. Open an animal profile.
  4. Log in with a demo account.
  5. Submit a new animal report.
  6. Upload or select an image.
  7. Run AI analysis.
  8. Review and edit AI-generated information.
  9. Submit the report.
  10. Confirm the new animal appears in listings and on the map.
  11. Review duplicate detection behavior.
  12. Open the adopter flow to see AI-assisted compatibility scoring.
  13. Submit a foster or rescue request.
  14. Visit the dashboard to review notifications and lifecycle updates.

Demo credentials

  • asha@example.com / demo123
  • admin@example.com / demo123

These are demo credentials for local use only.

Screenshots

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.

Future scope

  • 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

Limitations

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

Safety notice

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.

Disclaimer

AI-generated animal observations are not a veterinary diagnosis. Any AI-powered profile should be reviewed by a human before action is taken.

About

AI-powered stray-animal rescue, foster, and adoption platform.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages