Customer Website - Module Specification¶

1. Overview¶

1.1 Purpose¶

Public-facing storefront for puppy browsing, breed information, store locations, and lead capture. Customers can view available puppies with transparent pricing, research breeds, find store locations, explore financing options, and submit inquiries or reservation requests.

1.2 Scope¶

In Scope: - Puppy catalog with search and filtering - Individual puppy detail pages - Breed directory and detail pages - Store locator and store detail pages - Financing information pages - Content pages (About, Blog, Reviews, etc.) - Lead capture forms (Contact, Virtual Meet) - Marketing feed generation (Facebook, Google Ads)

Out of Scope: - Store check-in flows (→ CRM module) - Adoption/purchase transaction flow (→ Ecommerce module) - Admin dashboard and content editing (→ CMS module) - Lead management and follow-up (→ CRM module)

2. Dependencies¶

2.1 Upstream (What This Module Needs)¶

Module/Service	What We Need	Interface
Inventory	Puppy data, availability, pricing	Server Actions
CMS	Page content, blog posts, breed info	Server Actions
Media	Images, videos for puppies/breeds	Server Actions (R2 URL resolution)
Admin Settings	Store locations, brand config, virtual meet hours	Server Actions
Rich Text Editor	Render Lexical JSON content	React Component

2.2 Downstream (What Needs This Module)¶

Module/Service	What They Need	Interface
CRM	Lead submissions	Server Actions
Analytics	Page views, events	GTM/gtag
Social Media	Ad feed data	API endpoints

3. Data Ownership¶

3.1 Entities This Module Owns¶

Entity	Description	Key Fields
Lead	Customer inquiry/reservation request	id, name, email, phone, puppyId, source, message, createdAt

3.2 Entities This Module Uses (Read-Only)¶

Entity	Owner	How We Use It
Puppy	Inventory	Display in catalog and detail pages
Breed	Inventory	Display breed info and filter options
BreedCollection	Inventory	Group breeds for navigation
Store	Admin Settings	Display locations and details
Brand	Admin Settings	Site branding, virtual meet hours
Media	Media	Resolve images/videos for display
Blog	CMS	Display blog posts
LandingPage	CMS	Render CMS-driven content pages
Review	CMS	Display customer testimonials
VirtualLocation	CMS	SEO geo-targeting pages

3.3 Data Schema¶

interface Lead {
  id: string;
  name: string;
  email: string;
  phone: string;
  puppyId?: string;        // If inquiry about specific puppy
  breedId?: string;        // If inquiry about breed
  storeId?: string;        // Preferred store
  source: 'contact_form' | 'virtual_meet' | 'puppy_inquiry' | 'google_ads' | 'financing_form';
  message?: string;
  metadata?: Record<string, unknown>;
  createdAt: Date;
  updatedAt: Date;
}

4. Service Level Objectives¶

Objective	Target	Measurement
Page Load (LCP)	< 1s	Core Web Vitals
Availability	99.99%	Cloudflare analytics
Lighthouse SEO	100	CI automated testing
Lighthouse Accessibility	100	CI automated testing
Error Rate	< 0.1%	Error tracking

5. Interface Contract¶

5.1 Internal Service Interface¶

interface CustomerWebsiteService {
  // Lead capture
  submitLead(data: CreateLeadDTO): Promise<Lead>;

  // Virtual appointment
  bookVirtualMeet(data: VirtualMeetDTO): Promise<{ confirmationId: string }>;
}

interface CreateLeadDTO {
  name: string;
  email: string;
  phone: string;
  puppyId?: string;
  breedId?: string;
  storeId?: string;
  source: Lead['source'];
  message?: string;
}

interface VirtualMeetDTO {
  name: string;
  email: string;
  phone: string;
  scheduledDate: Date;      // Selected from calendar UI
  scheduledTime: string;    // Must be within brand's virtual meet hours
  puppyId?: string;
  notes?: string;
}

// Financing lead capture (required before accessing financing application)
interface FinancingLeadDTO {
  name: string;
  email: string;
  phone: string;
}

5.2 Remote Procedure Interface¶

Communication Pattern: Next.js Server Actions

Procedure	Input	Output	Auth	Description
submitContactForm	CreateLeadDTO	Lead	Public	Submit contact inquiry
submitPuppyInquiry	CreateLeadDTO	Lead	Public	Inquire about specific puppy
bookVirtualMeet	VirtualMeetDTO	Confirmation	Public	Book virtual appointment
submitFinancingLead	FinancingLeadDTO	Lead	Public	Capture name/phone/email before financing app

5.3 API Endpoints (Feeds)¶

Endpoint	Method	Output	Description
/api/feeds/facebook/all.csv	GET	CSV	Facebook ad feed - all puppies
/api/feeds/facebook/store/[slug].csv	GET	CSV	Facebook ad feed - by store
/api/feeds/google-ads/all	GET	CSV	Google Shopping feed
/api/webhooks/google-ads-lead	POST	JSON	Receive leads from Google Ads

6. Error Handling Strategy¶

Error Code	Condition	User Message
LEAD_INVALID_EMAIL	Invalid email format	"Please enter a valid email address"
LEAD_INVALID_PHONE	Invalid phone format	"Please enter a valid phone number"
LEAD_REQUIRED_FIELDS	Missing required fields	"Please fill in all required fields"
PUPPY_NOT_FOUND	Puppy doesn't exist	"This puppy is no longer available"
STORE_NOT_FOUND	Store doesn't exist	"Store not found"

Error Response Format¶

interface ErrorResponse {
  code: string;
  message: string;
  field?: string;  // For validation errors
}

7. Observability¶

7.1 Logging¶

Event	Level	Fields to Include
Lead submitted	INFO	lead_id, source, puppy_id
Page viewed	INFO	path, puppy_id, breed_id
Error occurred	ERROR	error_code, path, stack_trace

7.2 Metrics (via GTM Server-Side)¶

Event	Parameters	Description
page_view	page_path, page_title	Page views
view_item	item_id, item_name, price	Puppy detail views
view_item_list	item_list_name, items	Catalog views
generate_lead	lead_source, value	Lead submissions
select_content	content_type, item_id	Breed/store clicks

8. Testing Strategy¶

Test Type	Coverage Target	Tools	Focus Areas
Unit	80%+	Vitest	Form validation, data transforms
Integration	Critical paths	Playwright	Lead submission, navigation
E2E	Happy paths	Playwright	Puppy browsing, form submission
Visual	Key pages	Playwright	Responsive layouts
Accessibility	All pages	axe-core	WCAG 2.1 AA compliance

9. Feature Inventory¶

Puppy Catalog & Browsing¶

Feature ID	Name	Status	Priority
FEATURE-001	Home Page	Draft	Must Have
FEATURE-002	Puppies for Sale Catalog	Draft	Must Have
FEATURE-003	Puppy Filtering & Search	Draft	Must Have
FEATURE-004	Puppies by Breed/Collection	Draft	Must Have
FEATURE-005	Puppies Near Me	Draft	Should Have
FEATURE-006	New Arrivals	Draft	Should Have
FEATURE-007	Special Deals	Draft	Should Have
FEATURE-008	Puppy Detail Page	Draft	Must Have

Breeds¶

Feature ID	Name	Status	Priority
FEATURE-009	Breeds Directory	Draft	Must Have
FEATURE-010	Breed Detail Page	Draft	Must Have

Stores¶

Feature ID	Name	Status	Priority
FEATURE-011	Store Locator	Draft	Must Have
FEATURE-012	Store Detail Page	Draft	Must Have

Financing¶

Feature ID	Name	Status	Priority
FEATURE-013	Financing Overview	Draft	Must Have
FEATURE-014	Store Financing Page	Draft	Must Have
FEATURE-015	Financing Lead Capture	Draft	Must Have

FEATURE-015 Note: Requires name, phone, email before accessing financing application link.

Content¶

Feature ID	Name	Status	Priority
FEATURE-016	About Us	Draft	Should Have
FEATURE-017	Our Breeders	Draft	Should Have
FEATURE-018	Our Values	Draft	Should Have
FEATURE-019	Blog Listing	Draft	Should Have
FEATURE-020	Blog Post Detail	Draft	Should Have
FEATURE-021	Customer Reviews	Draft	Should Have

Lead Capture¶

Feature ID	Name	Status	Priority
FEATURE-022	Contact Form	Draft	Must Have
FEATURE-023	Puppy Inquiry Form	Draft	Must Have
FEATURE-024	Virtual Puppy Meet Booking	Draft	Should Have

FEATURE-024 Note: Calendar UI shows available slots based on brand settings. Only allows scheduling during store's configured virtual meet hours.

Utility¶

Feature ID	Name	Status	Priority
FEATURE-025	Thank You Pages	Draft	Must Have
FEATURE-026	404 Error Page	Draft	Must Have

Marketing Feeds¶

Feature ID	Name	Status	Priority
FEATURE-027	Facebook Ad Feed	Draft	Should Have
FEATURE-028	Google Ads Feed	Draft	Should Have
FEATURE-029	Google Ads Lead Webhook	Draft	Should Have

SEO¶

Feature ID	Name	Status	Priority
FEATURE-030	HTML Sitemap	Draft	Should Have
FEATURE-031	robots.txt	Draft	Must Have

10. Decisions¶

D1: Lead-Only Ownership (2026-01-19)¶

Status: Accepted Context: Customer Website needs to capture leads but not manage them Decision: Module owns Lead entity for creation only; CRM module manages lifecycle Consequences: Clean separation, but requires integration with CRM for follow-up

D2: Server Actions for Forms (2026-01-19)¶

Status: Accepted Context: Need type-safe form submissions without separate API Decision: Use Next.js Server Actions for all form submissions Consequences: Simpler architecture, automatic type inference

D3: GTM Server-Side for Analytics (2026-01-19)¶

Status: Accepted Context: Need comprehensive analytics without client-side bloat Decision: Use Google Tag Manager Server-Side container with gtag Consequences: Better privacy, faster pages, centralized tracking

11. References¶

Architecture: ARCH-001
Inventory Module: MODULE-002
Media Module: MODULE-003
Admin Settings Module: MODULE-004
Rich Text Editor Module: MODULE-005
Legacy Reference: https://BlueSkyPuppies.com
Legacy Codebase: https://git.apexmediamasters.app/10x/puppies-bsp-flp-hpu-marketing-websites
Features: ./MODULE-001-Customer-Website/

Change Log¶

Version	Date	Author	Changes
1.0	2026-01-19	Claude	Initial module spec - Approved
1.1	2026-01-20	Claude	Added references to Media, Admin Settings, Rich Text Editor modules
1.2	2026-01-20	Claude	Added SEO features: HTML Sitemap (FEATURE-030), robots.txt (FEATURE-031)