PetAd Frontend 🐾

A modern, responsive web application for pet adoption and temporary custody management, powered by blockchain-backed trust guarantees (Stellar trust layer integration).

---

Overview

PetAd Frontend is the client-side application for the PetAd platform, enabling users to browse pets, initiate adoption processes, and manage temporary custody arrangements. The application communicates exclusively with the PetAd backend API and does not directly interact with blockchain infrastructure.

---

✨ Features

• 🔍 Pet Browsing & Search - Discover available pets with advanced filtering
• ❤️ Adoption Workflows - Streamlined adoption process from inquiry to completion
• ⏰ Temporary Custody - Request and manage short-term pet care arrangements
• 👤 User Profiles - Personalized dashboards for pet seekers and caretakers
• 📄 Document Management - Secure upload and verification of required documents
• 🔔 Real-time Updates - Live status notifications for adoption and custody requests

---

🛠️ Tech Stack

Technology	Purpose
React 18+	UI library
TypeScript	Type-safe development
Vite	Build tool and dev server
Tailwind CSS	Utility-first styling
TanStack Query	Server state management
React Router	Client-side routing
Zod	Schema validation

---

📦 Prerequisites

Before you begin, ensure you have the following installed:

• Node.js >= 20.0.0
• npm >= 10.0.0 or pnpm >= 8.0.0

Check your versions:

node --version
npm --version

---

🚀 Getting Started

Installation

1. Clone the repository

git clone https://github.com/amina69/PetAd-Frontend.git
cd petad-frontend

2. Install dependencies

npm install

Or using pnpm:

pnpm install

---

Environment Setup

Create a .env file in the project root:

VITE_API_URL=http://localhost:3000

Note: VITE_API_URL should point to your PetAd backend API instance.

Optional environment variables:

VITE_APP_NAME=PetAd
VITE_ENABLE_ANALYTICS=false

---

Running the App

Start the development server:

npm run dev

The application will be available at:

http://localhost:5173

---

📁 Project Structure

src/
├── api/              # API client and service layer
│   ├── petService.ts
│   ├── adoptionService.ts
│   └── custodyService.ts
├── components/       # Reusable UI components
│   ├── common/
│   ├── layout/
│   └── forms/
├── features/         # Domain-specific features
│   ├── pets/
│   │   ├── components/
│   │   ├── hooks/
│   │   └── types/
│   ├── adoption/
│   └── custody/
├── hooks/            # Shared custom hooks
├── pages/            # Route-level components
├── utils/            # Helper functions and utilities
├── types/            # Global TypeScript types
├── main.tsx          # Application entry point
└── App.tsx           # Root component

Key Directories:

• api/ - Centralized API communication layer
• features/ - Feature-based architecture (pets, adoption, custody)
• components/ - Reusable, presentational components
• hooks/ - Custom React hooks for shared logic
• pages/ - Top-level route components

---

🧑‍💻 Development Guidelines

Code Style

• Use feature-based architecture for scalability
• Keep components small and focused (single responsibility)
• Validate all forms with Zod schemas
• Handle loading and error states explicitly
• Use TypeScript strict mode (no implicit any)

Component Example

// features/pets/components/PetCard.tsx
import { Pet } from '@/types/pet';

interface PetCardProps {
  pet: Pet;
  onAdopt: (petId: string) => void;
}

export function PetCard({ pet, onAdopt }: PetCardProps) {
  return (
    <div className="rounded-lg border p-4">
      <h3 className="font-semibold">{pet.name}</h3>
      <p className="text-sm text-gray-600">{pet.breed}</p>
      <button 
        onClick={() => onAdopt(pet.id)}
        className="mt-2 rounded bg-blue-500 px-4 py-2 text-white"
      >
        Adopt Me
      </button>
    </div>
  );
}

Validation Example

import { z } from 'zod';

const adoptionFormSchema = z.object({
  fullName: z.string().min(2, 'Name must be at least 2 characters'),
  email: z.string().email('Invalid email address'),
  phone: z.string().regex(/^\+?[1-9]\d{1,14}$/, 'Invalid phone number'),
  reason: z.string().min(50, 'Please provide more details'),
});

type AdoptionFormData = z.infer<typeof adoptionFormSchema>;

---

📜 Scripts

Command	Description
npm run dev	Start development server (hot reload enabled)
npm run build	Build optimized production bundle
npm run preview	Preview production build locally
npm run type-check	Run TypeScript compiler checks
npm run format	Format code with Prettier

---

Important: Ensure environment variables are configured in your deployment platform:

• VITE_API_URL - Backend API endpoint

---

🔗 API Communication

The frontend communicates with the PetAd backend API for all operations, including:

• User authentication
• Pet listings and details
• Adoption applications
• Custody requests
• Document uploads

Security:

• The frontend never holds private keys
• All blockchain transactions are processed server-side
• Authentication tokens are stored securely (HttpOnly cookies)

Example API Call:

import { useQuery } from '@tanstack/react-query';
import { petService } from '@/api/petService';

export function usePets() {
  return useQuery({
    queryKey: ['pets'],
    queryFn: () => petService.getAll(),
    staleTime: 5 * 60 * 1000, // 5 minutes
  });
}

---

🎨 Design Reference

This project follows a comprehensive design system documented in Figma. Please refer to the design files when implementing new features or components to ensure consistency.

📐 Figma Design File: PetAd Design System

The design includes:

• 🎨 Complete UI component library
• 📱 Responsive layouts for mobile, tablet, and desktop
• 🌈 Color palette and typography specifications
• 🔄 User flow diagrams for adoption and custody workflows
• ♿ Accessibility guidelines

Note for Developers: Always check the Figma design before building new components. Maintain pixel-perfect implementations where possible, and consult with the design team for any deviations.

---

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Before submitting:

• fix any issues
• Ensure npm run type-check passes
• Add tests for new features
• Update documentation if needed

---

📄 License

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

---

🙏 Acknowledgments

• Built with ❤️ for pet lovers everywhere
• Powered by blockchain technology for transparent, trustworthy pet adoption

---

Made with 🐾 by the PetAd Team