🐾 Pawlo

AI-Powered Lost Pet Reunification Platform

Reunite. Rescue. Repeat.

Live Demo • Report Bug • Request Feature

📖 About This Project

Pawlo is a mobile-first web application designed to help reunite lost pets with their owners through AI-powered photo matching and community collaboration. Built with modern web technologies, Pawlo connects neighborhoods to bring pets back home safely and quickly.

🎨 Created by MC Monkeys

This project was built by MC Monkeys — where humans and AI agents collaborate to build real-world digital solutions. MC Monkeys is the team behind Mission Control for Claude Code, a system that makes AI agent work visible in real time.

Pawlo was developed using this human-AI collaborative approach, combining strategic planning, modern development practices, and operational visibility to deliver a production-ready application.

Learn more: https://mcmonkeys.up.railway.app/

✨ Features

🔍 AI Photo Matching — Upload a photo of a found pet and get instant matches with registered pets
📱 Mobile-First Design — Optimized for on-the-go pet spotting and reporting
🐕 Pet Registration — Easy 4-step process to register your pet with photos and details
🏘️ Neighborhood Network — Connect with your community to help lost pets
🎯 Smart Filtering — Search by breed, size, color, and location
⚡ Real-Time Status — Track pets as Lost, Safe, or Reunited
📊 Success Stories — View reunited pets and community impact statistics
🎨 Beautiful UI — Modern, accessible design with smooth animations

🛠️ Tech Stack

Technology	Purpose
Next.js 14	React framework with App Router for optimal performance
TypeScript	Type-safe development and better developer experience
Tailwind CSS	Utility-first styling with custom design tokens
Lucide React	Beautiful, consistent icons
Vercel	Deployment platform (recommended)

📋 Prerequisites

Before you begin, ensure you have the following installed:

Node.js (v18.17 or higher)
npm (v9 or higher) or yarn / pnpm
Git for version control

🚀 Installation

Follow these steps to get Pawlo running on your local machine:

1. Clone the Repository

git clone https://github.com/billymcmonkeys/pawlo.git
cd pawlo

2. Install Dependencies

npm install

Or if you prefer yarn:

yarn install

3. Run the Development Server

npm run dev

Or with yarn:

yarn dev

4. Open in Browser

Navigate to http://localhost:3000 to see the application running.

The page will automatically reload when you make changes to the code.

📱 How to Use

For Pet Owners

Register Your Pet
- Navigate to the registration flow (/register)
- Upload 3-5 clear photos of your pet
- Fill in details (name, breed, size, color, distinctive features)
- Add your contact information
- Review and submit
Mark as Lost (if needed)
- Go to your pet's profile
- Update status to "Lost"
- Your neighborhood will be notified automatically
Reunite
- When your pet is found, update status to "Reunited"
- Share your success story!

For Community Members

Found a Pet?
- Go to /found/upload
- Upload a photo of the found pet
- Add location details
- Submit for AI matching
Review Matches
- View similarity-ranked results
- Contact the most likely owner
- Help reunite pets with their families

📂 Project Structure

pawlo/
├── app/                      # Next.js App Router
│   ├── layout.tsx            # Root layout
│   ├── page.tsx              # Home page
│   ├── how-it-works/         # Information pages
│   ├── register/             # Pet registration flow
│   │   ├── step-1/           # Photo upload
│   │   ├── step-2/           # Pet details
│   │   ├── step-3/           # Owner info
│   │   └── review/           # Final review
│   ├── found/                # Found pet flow
│   │   ├── upload/           # Upload found pet photo
│   │   ├── processing/       # AI matching process
│   │   ├── results/          # Match results
│   │   └── match/[id]/       # Individual match details
│   └── pets/[id]/            # Pet profile pages
├── components/               # Reusable React components
│   ├── Navbar.tsx
│   ├── PetCard.tsx
│   ├── StatusBadge.tsx
│   ├── HeroCarousel.tsx
│   └── ...
├── data/                     # Mock data (Phase 0)
│   ├── pets.ts               # Sample pets data
│   └── mock-results.ts       # Sample match results
├── lib/                      # Utility functions
│   ├── pets.ts               # Pet data helpers
│   ├── matches.ts            # Matching logic
│   └── store.ts              # State management
├── docs/                     # Documentation
│   ├── architecture.md       # Technical architecture
│   ├── wireframe-*.md        # Design wireframes
│   └── ...
├── public/                   # Static assets
├── next.config.js            # Next.js configuration
├── tailwind.config.ts        # Tailwind + design tokens
└── tsconfig.json             # TypeScript configuration

🎯 Available Scripts

Command	Description
`npm run dev`	Start development server at `localhost:3000`
`npm run build`	Create optimized production build
`npm run start`	Start production server
`npm run lint`	Run ESLint to check code quality
`npm run typecheck`	Run TypeScript type checking

🗺️ Roadmap

Phase 0 (Current) — Frontend Prototype

✅ Responsive UI/UX
✅ Mock data structure
✅ Complete user flows
✅ Design system implementation

Phase 1 — Backend Integration

⏳ Database setup (Prisma + PostgreSQL)
⏳ REST API endpoints
⏳ Real data persistence
⏳ User authentication

Phase 2 — AI Integration

⏳ Real AI photo matching API
⏳ Improved matching algorithms
⏳ Confidence scoring

Phase 3 — Advanced Features

⏳ Push notifications
⏳ Geolocation services
⏳ In-app messaging
⏳ Social sharing
⏳ Multi-language support

🌟 Key Features in Detail

AI Photo Matching

Upload a photo and our AI compares it against registered pets, ranking matches by similarity score based on visual features like:

Breed characteristics
Coat color and patterns
Size and body structure
Distinctive markings

Multi-Step Registration

A user-friendly 4-step wizard guides pet owners through registration:

Photo Upload — Multiple angles for better matching
Pet Details — Comprehensive information capture
Owner Contact — Secure contact method storage
Review — Verify before submission

Community Dashboard

View neighborhood statistics:

Total pets reunited
Average reunification time
Active registered pets
Lost pet alerts

🐛 Known Issues & Limitations

Current Limitations (Phase 0)

No Backend: All data is mock/static
No Persistence: Refreshing the page resets state
No Authentication: No user accounts or login
Simulated AI: Matches are pre-defined, not computed

These limitations are intentional for the prototype phase and will be addressed in future updates.

🤝 Contributing

We welcome contributions! If you'd like to contribute:

Fork the repository
Create a feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Please ensure your code follows the existing style and passes all linting checks.

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

📞 Contact & Support

Project Creator: MC Monkeys

MC Monkeys is a human-AI collaborative system building real-world digital solutions. The team uses Claude Code agents with full operational visibility through Mission Control.

🌐 Website: https://mcmonkeys.up.railway.app/
🎯 Mission Control: Live Demo
📖 Our Story: Read the Story
💼 GitHub: @billymcmonkeys
📧 Email: billy.mcmonkeys@gmail.com

Need Help?

🙏 Acknowledgments

Built using human-AI collaborative workflows with Claude Code agents
Developed with full operational visibility through MC Monkeys Mission Control
Pet photos courtesy of Unsplash and placeholder services
Icons by Lucide
Inspired by real-world pet reunification challenges
Built with ❤️ for pet lovers everywhere

🐾 Help us bring more pets home safely! 🐾

Visit MC Monkeys | Star this repo ⭐

Built with human-AI collaboration by MC Monkeys 🐵

Making AI agent work visible. One project at a time.

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
app		app
components		components
data		data
docs		docs
lib		lib
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
README.md		README.md
next.config.js		next.config.js
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

🐾 Pawlo

AI-Powered Lost Pet Reunification Platform

📖 About This Project

🎨 Created by MC Monkeys

✨ Features

🛠️ Tech Stack

📋 Prerequisites

🚀 Installation

1. Clone the Repository

2. Install Dependencies

3. Run the Development Server

4. Open in Browser

📱 How to Use

For Pet Owners

For Community Members

📂 Project Structure

🎯 Available Scripts

🗺️ Roadmap

Phase 0 (Current) — Frontend Prototype

Phase 1 — Backend Integration

Phase 2 — AI Integration

Phase 3 — Advanced Features

🌟 Key Features in Detail

AI Photo Matching

Multi-Step Registration

Community Dashboard

🐛 Known Issues & Limitations

Current Limitations (Phase 0)

🤝 Contributing

📄 License

📞 Contact & Support

Project Creator: MC Monkeys

Need Help?

🙏 Acknowledgments

🐾 Help us bring more pets home safely! 🐾

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages