🐾 AdoptPaws

A full-stack pet adoption web application that connects loving families with pets waiting for their forever homes. Built with React 19, Express.js, and Firebase Firestore.

Features

• Pet Browsing — Browse adoptable pets with filters for species, size, gender, and age category
• Pet Details — View detailed profiles with image galleries, bios, vital stats, and related pets
• Adoption Applications — Multi-section form (personal info, home environment, pet experience) submitted to Firestore
• Favorites — Save and view favorite pets in a bento-grid layout
• Sign In / Profile — Authentication page with Google and Apple social login options
• Responsive Design — Mobile-first layout with Material Design 3 inspired theming and organic/asymmetric card shapes

Tech Stack

Layer	Technology
Frontend	React 19, TypeScript, Vite 6
Styling	Tailwind CSS v4, custom MD3 theme tokens
Routing	React Router v7
Animations	Motion (Framer Motion)
Icons	Material Symbols, Lucide React
Backend	Express.js 4
Database	Firebase Firestore (via firebase-admin)
Auth	Firebase Authentication (Google provider)
Validation	Zod
Deployment	Docker, Google Cloud Run, Cloud Build

Project Structure

├── src/
│   ├── main.tsx              # App entry point
│   ├── App.tsx               # Router configuration
│   ├── index.css             # Global styles, MD3 theme tokens, custom utilities
│   ├── api/
│   │   └── pets.ts           # Frontend API client (fetchPets, fetchPet, submitApplication)
│   ├── components/
│   │   ├── Navbar.tsx         # Fixed top navigation bar
│   │   └── Footer.tsx         # Site footer with links
│   ├── data/
│   │   └── pets.ts           # Pet type definition and seed data (6 pets)
│   ├── layouts/
│   │   └── MainLayout.tsx     # Navbar + Outlet + Footer wrapper
│   └── pages/
│       ├── Home.tsx           # Landing page with hero, how-it-works, featured pets, CTA
│       ├── PetList.tsx        # Browsable pet grid with sidebar filters
│       ├── PetDetails.tsx     # Individual pet profile with gallery and adoption CTA
│       ├── Favorites.tsx      # Saved pets in bento-grid layout
│       ├── Apply.tsx          # Adoption application form
│       └── Profile.tsx        # Sign-in / authentication page
├── server/
│   ├── server.ts             # Express API server with pet and application routes
│   ├── firestore.ts          # Firebase Admin SDK initialization
│   └── seed.ts               # Database seeder script
├── Dockerfile                # Multi-stage build (Node 20)
├── cloudbuild.yaml           # Google Cloud Build CI/CD pipeline
├── deploy.sh                 # One-command Cloud Run deployment script
├── vite.config.ts            # Vite config with proxy to backend
├── tsconfig.json             # Frontend TypeScript config
└── tsconfig.server.json      # Server TypeScript config

Prerequisites

• Node.js 20+
• Google Cloud Project with Firestore enabled
• gcloud CLI authenticated (gcloud auth application-default login)

Getting Started

1. Install dependencies

npm install

2. Configure environment

Copy the example env file and fill in your values:

cp .env.example .env.local

GOOGLE_CLOUD_PROJECT=your-gcp-project-id
PORT=3001

# Firebase Web SDK (frontend) — NOT secret, identifies the project
VITE_FIREBASE_API_KEY=your-firebase-web-api-key
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-gcp-project-id

Firebase Authentication

Sign-in uses Firebase Authentication with the Google provider.

1. In the Firebase console, open your project → Authentication → Sign-in method → enable Google.
2. Open Project settings → General → "Your apps" → register a Web app and copy the apiKey, authDomain, projectId into .env.local using the VITE_FIREBASE_* variables above.
3. To gate admin-only routes (pet CRUD, listing all applications), sign in once to create your user, then grant yourself the admin custom claim:

tsx server/scripts/grantAdmin.ts <your-uid>

The user must sign out and back in for the claim to take effect on the client.

3. Seed the database

Populate Firestore with sample pet data (6 pets — dogs and cats):

npm run seed

4. Run locally

Starts both the Vite dev server (port 3000) and Express API server (port 3001) concurrently:

npm run dev

The frontend proxies /api requests to the backend automatically.

Available Scripts

Script	Description
npm run dev	Start frontend + backend concurrently
npm run dev:client	Start Vite dev server only (port 3000)
npm run dev:server	Start Express server with hot reload (port 3001)
npm run build	Build frontend with Vite
npm run build:server	Compile server TypeScript
npm run build:all	Build both frontend and server
npm run start	Start production server
npm run seed	Seed Firestore with sample pet data
npm run lint	Type-check with TypeScript
npm run clean	Remove build artifacts

API Endpoints

Mutating and admin endpoints require a Firebase ID token in the Authorization: Bearer <token> header. Admin-only routes additionally require the admin: true custom claim (see Firebase Authentication).

Pets

Method	Endpoint	Auth	Description
GET	/api/pets	—	List all pets (supports species, size, gender, ageCategory query filters)
GET	/api/pets/:id	—	Get a single pet by ID
POST	/api/pets	admin	Create a new pet
PUT	/api/pets/:id	admin	Update a pet
DELETE	/api/pets/:id	admin	Delete a pet

Applications

Method	Endpoint	Auth	Description
POST	/api/applications	user	Submit an adoption application (server stamps userId)
GET	/api/applications	admin	List all applications

Favorites

Method	Endpoint	Auth	Description
GET	/api/favorites	user	List the current user's favorited pet IDs
PUT	/api/favorites/:petId	user	Add a pet to favorites
DELETE	/api/favorites/:petId	user	Remove a pet from favorites

Deployment

Option A: Deploy script

./deploy.sh <GCP_PROJECT_ID> [REGION] [SERVICE_NAME]

# Example:
./deploy.sh my-gcp-project us-central1 adoptpaws

Required GCP APIs:

• Cloud Run
• Cloud Build
• Artifact Registry
• Firestore

Enable them with:

gcloud services enable run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com \
  firestore.googleapis.com

Option B: Cloud Build

gcloud builds submit --config cloudbuild.yaml \
  --substitutions=_REGION=us-central1,_SERVICE_NAME=adoptpaws

Docker (manual)

docker build -t adoptpaws .
docker run -p 8080:8080 \
  -e NODE_ENV=production \
  -e GOOGLE_CLOUD_PROJECT=your-project-id \
  adoptpaws

The Dockerfile uses a multi-stage build: stage 1 builds the Vite frontend and compiles the server TypeScript, stage 2 copies only production artifacts and dependencies.

Design System

The app uses a custom Material Design 3 inspired theme defined in src/index.css with:

• Fonts: Plus Jakarta Sans (headings), Be Vietnam Pro (body)
• Color tokens: Full MD3 surface/primary/secondary/tertiary/error palette
• Custom utilities: organic-shape / organic-card / asymmetric-card for distinctive rounded corners (3rem top-left/bottom-right, 1rem top-right/bottom-left)
• Background: Subtle radial gradient mesh (bg-mesh)

Routes

Path	Page	Layout
/	Home	MainLayout
/pets	Pet listing with filters	MainLayout
/pets/:id	Pet detail page	MainLayout
/favorites	Saved favorites	MainLayout
/apply/:petId	Adoption application	MainLayout
/profile	Sign in / profile	Full screen (no layout)

License

Apache-2.0