The social network where your pet is the star.
PetCircle is a PWA platform where pet owners create profiles for their pets, share moments in a social feed, manage health and routines with smart reminders, exchange direct messages, and discover pets in their area.
Current status: 18 sprints completed. Phases 1, 2, and 3 are done. Phase 4 (Marketplace) is planned.
| Layer | Technology |
|---|---|
| Package Manager | pnpm |
| Framework | Next.js 16 (App Router) + React 19 + TypeScript strict |
| Styling | Tailwind CSS v4 (custom @theme tokens) + Framer Motion (spring animations) |
| Backend | Supabase (PostgreSQL 17 + Auth + Storage + Realtime) |
| Auth | Google OAuth + Email/Password with email confirmation |
| Forms | react-hook-form + Zod v4 |
| i18n | next-intl (pt-BR default + en, cookie-based without URL prefix) |
| Push | Web Push API (custom service worker + VAPID) |
| Lint/Format | Biome (no ESLint, no Prettier) |
| Hosting | Vercel + Supabase Cloud |
- Google OAuth login
- Email/password login/signup with email confirmation
- Account merging by email
- 3-step onboarding on first login (name + photo → species + breed → birthday + city)
- Soft-delete account with a 30-day grace period
- Infinite scroll with pagination
- Post creation with photo (client-side compression) + caption + mood (7 mood states)
- Paw 🐾 likes (pet-centric vocabulary, not hearts) — persona-aware: like as owner or as pet
- Double-tap to like on mobile
- Threaded comments (1 level — replies to replies become siblings of the parent)
- Sharing via Web Share API + direct link
- Favorites (save posts to a private list)
- Edit and delete posts by the author
- Create, edit, and delete (soft-delete 30 days + hard delete)
- Avatar, name, species, breed, birth date, bio, personality (tags)
- Post gallery, counters (posts / fans / pet-friends)
- SEO with Open Graph and Twitter Cards (
generateMetadata) - Slug-based canonical URLs (
/pet/rex-muttinstead of UUID) - Co-ownership: invite other users to co-manage the same pet via invite link (30-day expiration)
- Vaccination record with date, batch, veterinarian, prescription (PDF/image in private bucket)
- Health events timeline
- Alerts for expired vaccines / upcoming doses
- Types: feeding, medication, grooming, exercise, veterinary, custom
- Scopes: per-pet, all pets (owner-wide), personal (owner)
- Frequencies: one-time, daily, weekly, monthly
- Smart food tracking: suggests next feeding based on purchase history
- 1:1 chat owner ↔ owner (not pet ↔ pet)
- Send messages as pet or as owner (persona-aware)
- Realtime via Supabase (instant message delivery)
- Presence (who is online in the conversation)
- Unread count in BottomNav
- Push notification if recipient is not in an active chat
- Grid of pets sorted by fans
- Search by name/breed (debounce + pg_trgm indexes)
- Species filters
- “Near you” section based on pet’s city
- Infinite scroll
- Toggle between interacting as owner or as pet
active-personacookie shared between SSR and client- Affects likes, comments, and sent messages
- In-app: like, comment, reply, follow, badge earned
- Web Push for direct messages (with user permission)
- Unread badge in BottomNav (realtime)
- Self-action rules (no notification if owner likes their own pet, but notify if pet A comments on pet B from the same owner)
- 8 badges:
first_post,loved_10,popular_50,influencer_100,vaccinated,consistent_7,birthday,social_butterfly - Automatic unlock via triggers (post_created, like_received, follow_received, vaccine_updated, reminder_completed)
- Notification when a badge is unlocked
manifest.jsonwithdisplay: standalone,theme_color: #7C3AED- Custom Service Worker (cache-first for static assets, push listener, notification click handler)
- Icons 192×192 and 512×512 (PNG + SVG, Android maskable)
- Apple Web App meta tags (iOS add to home screen)
- pt-BR (default) + en
- Cookie-based (no URL prefix, preserves SEO)
pnpm i18n:checkscript validates keys in both locales- Zero hardcoded strings in UI (mandatory rule in
.claude/rules/i18n.md)
git clone https://github.com/your-username/petcircle.git
cd petcircle
pnpm install
# Local Supabase (requires Docker Desktop running)
pnpm dlx supabase start
pnpm dlx supabase db reset # applies all 39 migrations
# Environment variables
cp .env.example .env.local
# Edit .env.local with values from `supabase status`:
# NEXT_PUBLIC_SUPABASE_URL
# NEXT_PUBLIC_SUPABASE_ANON_KEY
# SUPABASE_SERVICE_ROLE_KEY
# Generate VAPID keys for Web Push
npx tsx scripts/generate-vapid-keys.ts
# Paste into .env.local:
# NEXT_PUBLIC_VAPID_PUBLIC_KEY
# VAPID_PRIVATE_KEY
# (Optional) Seed IBGE cities
pnpm db:seed-cities
pnpm devOpen http://localhost:3000.
For production deployment, see DEPLOYMENT.md.
pnpm dev # Dev server (localhost:3000)
pnpm build # Production build
pnpm start # Serve local build
pnpm biome:check # Lint + format check
pnpm biome:fix # Lint + format auto-fix
pnpm type-check # TypeScript strict
pnpm i18n:check # Validate i18n keys (pt-BR + en)
pnpm db:seed-cities # Populate cities table with IBGE data(kept identical — already language-agnostic and clear)
| Phase | Sprints | Focus | Status |
|---|---|---|---|
| 1 — MVP Core | 1–6 | Auth, Pet Profile, Feed, Follow, Basic Reminders | ✅ Complete |
| 2 — Social & Location | 7–10 | Forms, search, location, co-ownership, multiple pets | ✅ Complete |
| 3 — Engagement | 11–18 | Persona, comments, DMs, health, notifications, badges | ✅ Complete |
| 4 — Marketplace | 19+ | Pet services, scheduling, monetization | 🔜 Planned |
Sprints 19–21 in progress: documentation, installable PWA, OG link preview, SOLID refactor. See tasks/backlog.md.
| Document | Description |
|---|---|
| docs/FEATURES.md | Canonical map of each feature (routes, actions, components, tables) |
| docs/ARCHITECTURE.md | Architectural decisions with rationale + Mermaid flows |
| docs/DATABASE.md | Full ERD + live schema per table |
| docs/NOTIFICATIONS.md | Events → notification/push/email, Web Push setup |
| docs/BADGES.md | 8 badges, triggers, guide to add new badges |
| docs/PWA.md | Installation, service worker, OG images, troubleshooting |
| docs/API-REFERENCE.md | All Server Actions and API routes |
| docs/design-system.md | Color palette, typography, components, animations |
| docs/ux-principles.md | 7 UX principles and tone of voice |
MIT