PawSphere

PawSphere: Your vet, nutritionist, and pet concierge in one effortless app.

Comment

PawSphere - Complete Project Documentation

Project Overview

PawSphere is a comprehensive pet care platform that brings everything pet-related into one unified application. It's like having a vet, nutritionist, groomer, and pet concierge all in a single, beautiful app.

Inspiration

PawSphere was born from the frustration of fragmented pet care. Pet owners juggle separate apps for vet appointments, pet adoption, grooming booking, nutrition tracking, and medical records. We wanted to create a unified platform that brings everything under one roof - like a Swiss Army knife for pet owners. The goal was to make pet ownership less stressful and more accessible by combining modern AI technology with beautiful user interfaces.

What it Does

Core Features:

  • Pet Adoption Marketplace: Browse & adopt from verified shelters and ethical breeders
  • AI Health Triage: Instant pet symptom analysis powered by Gemini AI (50+ symptom patterns)
  • Smart Nutrition: 7-day meal plans and food safety tools
  • Grooming Booking: Find & schedule grooming salons nearby
  • Pet Shopping Hub: Integrated marketplace for pet supplies & accessories
  • Digital Passport: Complete health records, vaccines, microchip tracking
  • Pet Matchmaking: AI-powered compatibility quiz for finding your perfect pet
  • Community: Connect with other pet owners
  • Emergency Response: Quick access to emergency vet info
  • 3D Digital Twin: Interactive 3D visualization of pets with organ system mapping

Species Support:

  • Dogs, Cats, Birds, Fish, Reptiles, Rabbits, Horses, Turtles, Snakes, Hamsters, and more

How We Built It

Tech Stack:

  • Frontend: React 18 + TypeScript + Vite
  • 3D Visualization: Three.js + @react-three/fiber + @react-three/drei
  • Mapping: Leaflet + react-leaflet
  • AI Integration: Gemini AI (@google/generative-ai)
  • Backend: Supabase (Authentication & Database)
  • Styling: Tailwind CSS + Framer Motion
  • Icons: Lucide React
  • Build Tool: Vite

Project Architecture:

pawsphere-main/
├── src/
│   ├── components/
│   │   ├── views/           # Main feature views (18+ views)
│   │   ├── three/          # 3D visualization components
│   │   ├── modals/         # Authentication & pet modals
│   │   ├── layout/         # Navigation & layout components
│   │   ├── grooming/       # Grooming-specific components
│   │   └── maps/          # Map components
│   ├── lib/
│   │   └── api/           # API modules (10+ API services)
│   ├── hooks/             # Custom React hooks
│   ├── types/             # TypeScript type definitions
│   ├── data/              # Mock data & external data
│   └── db/                # Database storage utilities
├── public/
│   ├── models/animals/    # 3D GLB models (9+ species)
│   └── images/           # Pet fallback images
└── supabase/
    └── migrations/       # Database schema

Key Technical Decisions:

  1. TypeScript: For type safety and better developer experience
  2. React Hooks: Functional components with custom hooks for state management
  3. Modular Architecture: Separated concerns into specialized API modules
  4. Dynamic Imports: Lazy loading for heavy 3D components
  5. Glass Morphism Design: Modern UI with depth and texture
  6. Species-Specific Configs: Each animal type has unique health parameters and UI presentation

Challenges We Ran Into

1. Complex 3D Integration

  • Getting different animal GLB models to load properly
  • Species-specific animations and organ mapping
  • Performance optimization for web delivery
  • Coordinate system alignment for organ pins

2. AI Symptom Analysis

  • Creating reliable emergency detection algorithms
  • Medical research for accurate triage levels
  • Handling 50+ symptom patterns with appropriate care guidance
  • Balancing AI responses with veterinary disclaimer requirements

3. Species-Specific Logic

  • Each animal type needed completely different:
    • Health parameters (heart rates from 36 BPM for horses to 360 BPM for hamsters)
    • Nutritional requirements
    • UI presentation and terminology
    • Emergency response protocols

4. State Management

  • Handling multiple pets per user
  • Complex authentication flows
  • Form states across the application
  • Real-time vs mock data handling

5. Leaflet Integration

  • Dynamic markers with custom popups
  • User location tracking and geolocation
  • Map performance with multiple shelters
  • Tile layer configuration and attribution

6. Project Organization

  • Duplicate folder structure (pawsphere-main/ vs root)
  • File organization for scalability
  • Import path management
  • Build configuration

Accomplishments We're Proud Of

1. Comprehensive Symptom Analyzer

  • 50+ symptom patterns analyzed
  • Emergency detection for:
    • Anaphylaxis & severe allergic reactions
    • Urinary blockages (especially critical for male cats)
    • Seizures and neurological emergencies
    • Major trauma and respiratory distress
  • Four-tier severity system:
    • EMERGENCY (immediate veterinary care)
    • URGENT VETERINARY CARE (within 24 hours)
    • VETERINARY CHECK RECOMMENDED (schedule appointment)
    • MONITOR AT HOME (minor issues)

2. Species-Specific 3D Viewer

  • 9 animal species with accurate anatomical positioning:
    • Dogs: Heart at [0.1, 0.4, 0.3], joints at [-0.4, -0.2, -0.4]
    • Cats: Heart at [0.1, 0.35, 0.25], different target height
    • Birds: Flight stamina metrics, wing joint mapping
    • Fish: Hydro-stamina calculations, gill health
    • Horses: Massive cardiovascular engine visualization
    • Reptiles: Ectothermic heart rate adjustments
  • Dynamic configuration system with species-specific:
    • Organ pin positions
    • Color schemes
    • Treatment plans
    • Health test scenarios

3. Complete Pet Ecosystem

  • Integrated features in one platform:
    • Adoption → Health → Nutrition → Grooming → Shopping
    • Seamless user flow from pet selection to ongoing care
    • Unified pet profile across all features

4. Beautiful UI/UX

  • Glass-morphism design with modern aesthetics
  • Responsive layouts for all screen sizes
  • Smooth animations and transitions
  • Intuitive navigation with clear visual hierarchy
  • Accessibility considerations in color contrast and text sizes

5. Scalable Architecture

  • Modular component design that can be extended
  • API layer abstraction for easy backend swapping
  • TypeScript interfaces for type safety
  • Custom hooks for reusable logic
  • Configuration-driven species system

6. Medical Accuracy

  • Extensive veterinary research incorporated
  • Proper first-aid guidance for emergencies
  • Species-specific medical advice
  • Follow-up questions for veterinary consultations
  • Red flag detection for critical symptoms

What We Learned

1. Pet Health Complexity

  • Digestive Systems: Rabbits need continuous digestion, cats are prone to hairballs
  • Heart Rates: Vary wildly (36 BPM for horses, 360 BPM for hamsters)
  • Emergency Signs: Different species show distress differently
  • Nutritional Needs: Carnivores vs herbivores vs omnivores
  • Environmental Factors: Temperature, humidity, lighting needs vary

2. 3D Performance Optimization

  • GLB model compression techniques
  • Dynamic loading strategies
  • Camera positioning for different species
  • Animation blending and state management
  • Texture optimization for web delivery

3. Emergency Prioritization

  • Triage levels based on symptom severity
  • Time-sensitive emergencies (urinary blockages in cats)
  • Species-specific red flags (open-mouth breathing in cats)
  • First-aid vs professional care boundaries
  • When to escalate vs when to monitor

4. Species-Specific UI Design

  • Different metaphors for different pets
  • Terminology adjustments (beak vs teeth, scales vs fur)
  • Color coding by species
  • Icon selection for intuitive understanding
  • Information density adjustments

5. API Integration Strategies

  • Real-time data with fallback mock data
  • Error handling for external API failures
  • Caching strategies for performance
  • Loading states and user feedback
  • Authentication flow management

6. Project Organization Best Practices

  • Clear folder structure from the start
  • Avoiding duplication in source control
  • Consistent naming conventions
  • Documentation importance
  • Environment variable management

What's Next for PawSphere

Phase 1: Immediate Enhancements

  1. Mobile Apps: Launch iOS and Android versions
  2. Offline Support: Core features available without internet
  3. Push Notifications: Medication reminders, appointment alerts
  4. Multi-language Support: International expansion

Phase 2: Advanced Features

  1. Veterinarian Portal: Tools for vets to manage client pets
  2. Pet Insurance Integration: Claims processing and coverage checking

  3. Smart Device Integration:

    • Pet cameras with motion detection
    • Smart feeders with portion control
    • Health monitors (activity, sleep, temperature)
    • GPS trackers for outdoor pets

  4. Advanced AI Capabilities:

    • Image recognition for symptom analysis
    • Breed identification from photos
    • Behavioral pattern analysis
    • Predictive health alerts

Phase 3: Community & Marketplace

  1. Pet Social Network:

    • Photo sharing and pet profiles
    • Local pet owner meetups
    • Experience sharing and advice

  2. Peer-to-Peer Services:

    • Pet sitting and boarding marketplace
    • Dog walking services
    • Pet training sessions
    • Grooming at home services

  3. Business Integration:

    • Veterinary clinic management tools
    • Pet store inventory integration
    • Grooming salon booking systems
    • Breeder network platform

Phase 4: Global Expansion

  1. Regional Adaptation:

    • Local veterinary guidelines per country
    • Regional pet adoption laws
    • Local pet supply chains
    • Cultural pet care practices

  2. Enterprise Solutions:

    • Animal shelters management system
    • Veterinary clinic software
    • Pet food company partnerships
    • Insurance provider integrations

Deployment Instructions

Prerequisites:

  • Node.js 18+ and npm
  • Supabase account with project
  • Gemini API key
  • GitHub account for Vercel deployment

Environment Variables:

VITE_SUPABASE_URL=https://your-project-ref.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key-here
VITE_GEMINI_API_KEY=your-gemini-key-here

Local Development:

npm install
npm run dev

Vercel Deployment:

  1. Push code to GitHub repository
  2. Connect to Vercel via GitHub OAuth
  3. Import project with auto-detected settings
  4. Add environment variables in Vercel dashboard
  5. Deploy with automatic CI/CD

Technical Metrics

  • Components: 60+ React components
  • 3D Models: 9 animal species with GLB models
  • API Modules: 12+ specialized API services
  • TypeScript Types: 30+ type definitions
  • Symptom Patterns: 50+ analyzed patterns
  • UI States: 100+ unique component states

Development Commands

# Development
npm run dev          # Start development server
npm run build        # Production build
npm run preview      # Preview production build
npm run lint         # Lint code

# Testing (to be added)
npm run test         # Run tests
npm run test:watch   # Watch mode tests
npm run test:coverage # Test coverage report

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make changes with TypeScript type safety
  4. Add tests for new features
  5. Update documentation
  6. Submit pull request

License

[Add appropriate license here - MIT recommended for open source]

Acknowledgments

  • Veterinary professionals for medical guidance
  • 3D model creators for animal assets
  • Open source community for libraries
  • Pet owners for feedback and testing

Design Philosophy

PawSphere follows these design principles:

  1. Pet-Centric: Every decision made with pets' well-being first
  2. User-Friendly: Complex features presented simply
  3. Medically Accurate: Professional veterinary guidance integrated
  4. Visually Engaging: Modern, beautiful interfaces that users enjoy
  5. Accessible: Features available to all pet owners regardless of tech skills
  6. Scalable: Architecture designed for future growth
  7. Integrated: All pet care aspects in one place

Emergency Features

Detected Emergencies:

  1. Anaphylaxis: Facial swelling + itching
  2. Respiratory Distress: Difficulty breathing, blue gums
  3. Major Trauma: Hit by car, falls, fractures
  4. Seizures: Convulsions, collapse
  5. Urinary Blockage: Straining to urinate with no output (critical for male cats)
  6. Heat Stroke: Extreme temperature exposure
  7. Toxin Ingestion: Known poisonous substances

Response System:

  • Immediate action steps for each emergency
  • Veterinary contact information based on location
  • Transport guidance for critical cases
  • Follow-up care instructions

Last Updated: September 11, 2026 Project Status: Production Ready and Vercel Deployed

Built With

Share this project:

Updates

Submission history