Puppies OS - Architecture Specification¶

1. Overview¶

This architecture implements VISION-001 - a digital operating system for puppy stores providing customer-facing ecommerce/lead generation and operational tools, deployed as independent instances for 3 brands.

2. Constraints¶

2.1 Technical Constraints¶

Constraint	Rationale
Single codebase, 3 deployments	One source of truth for maintainability
Edge-first architecture	Cloudflare Workers for global performance
Instance data isolation	Separate brands in separate markets
TypeScript throughout	Type safety, better DX, fewer runtime errors

2.2 Business Constraints¶

Constraint	Rationale
Start simple, add complexity when needed	Avoid over-engineering
Self-service content editing	Staff must edit without developers
Cost-effective hosting	3 instances must be affordable

3. Quality Attributes¶

Attribute	Requirement	Measurement
Performance	Page load < 1s	Lighthouse, Core Web Vitals
SEO	Lighthouse SEO = 100	Automated CI testing
Accessibility	Lighthouse A11y = 100	Automated CI testing
Availability	99.99% uptime	Monitoring dashboards
Mobile	Mobile-first responsive	Device testing

4. System Context¶

4.1 Users¶

User Type	Description	Primary Goals
Customer (Buyer)	Potential puppy buyer	Browse puppies, see prices, inquire/reserve
Store Sales Staff	In-store sales	Manage walk-ins, close sales
Phone Sales Staff	Remote sales	Handle inquiries, phone reservations
Puppy Content Creator	Content team	Add/update puppy listings, photos
Web Content Editor	Marketing	Edit pages, blog, landing pages
Warranty Department	Post-sale support	Manage warranties, customer issues
Admin/Owner	Business owner	Analytics, settings, full access

4.2 External Systems¶

System	Integration	Data Flow
Resend	API	Outbound (remarketing, notifications)
YouTube API	API	Outbound (video publishing)
Meta API (Facebook/Instagram)	API	Outbound (posts, reels)
TikTok API	API	Outbound (video publishing)
Cloudflare R2	S3 API	Bidirectional (puppy photos, media)
Square Payments	API	Bidirectional (deposits, payments)
DocuSeal	API	Bidirectional (contracts, agreements)
Google Tag Manager (Server-Side)	gtag	Outbound (analytics events)

5. Container Architecture¶

┌─────────────────────────────────────────────────────────────────┐
│                     Cloudflare Workers (Edge)                   │
│                         via OpenNext                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ┌────────────────────────────────────────────────────────┐    │
│   │               Next.js Application                      │    │
│   │                   Bun Runtime                          │    │
│   ├────────────────────────────────────────────────────────┤    │
│   │                                                        │    │
│   │   ┌─────────────────┐    ┌─────────────────────────┐   │    │
│   │   │  Customer Site  │    │    Admin Dashboard      │   │    │
│   │   │  - Home         │    │    - /admin/*           │   │    │
│   │   │  - Puppies      │    │    - Inventory mgmt     │   │    │
│   │   │  - Breeds       │    │    - CRM / Leads        │   │    │
│   │   │  - Blog         │    │    - Analytics          │   │    │
│   │   │  - Contact      │    │    - Content CMS        │   │    │
│   │   │  - Reservations │    │    - Remarketing        │   │    │
│   │   └─────────────────┘    │    - Social media       │   │    │
│   │                          │    - Price forecasting  │   │    │
│   │                          └─────────────────────────┘   │    │
│   │                                                        │    │
│   │   ┌─────────────────────────────────────────────────┐  │    │
│   │   │           Server Actions (API Layer)            │  │    │
│   │   │   - Drizzle ORM (type-safe DB access)           │  │    │
│   │   │   - Better Auth (authentication)                │  │    │
│   │   └─────────────────────────────────────────────────┘  │    │
│   │                                                        │    │
│   │   ┌─────────────────────────────────────────────────┐  │    │
│   │   │                  UI Layer                       │  │    │
│   │   │   - Tailwind CSS                                │  │    │
│   │   │   - shadcn/ui components                        │  │    │
│   │   └─────────────────────────────────────────────────┘  │    │
│   │                                                        │    │
│   └────────────────────────────────────────────────────────┘    │
│                              │                                  │
└──────────────────────────────┼──────────────────────────────────┘
                               │
              ┌────────────────┼────────────────┐
              ▼                ▼                ▼
┌─────────────────────┐ ┌─────────────┐ ┌─────────────────────┐
│  DigitalOcean       │ │ Cloudflare  │ │  External APIs      │
│  Managed PostgreSQL │ │ R2 Storage  │ │  - Email            │
│                     │ │             │ │  - E-signature      │
│                     │ │             │ │  - Social           │
│                     │ │             │ │  - Payments         │
└─────────────────────┘ └─────────────┘ └─────────────────────┘

5.1 Containers¶

Container	Technology	Responsibility
Web Application	Next.js (App Router)	SSR pages, Server Actions, routing
Runtime	Bun	Fast JS runtime
Edge Adapter	OpenNext	Deploy Next.js to Cloudflare Workers
Caching	OpenNext R2 Cache	Next.js ISR/caching via R2
Query Accelerator	Cloudflare Hyperdrive	PostgreSQL connection pooling and query caching
ORM	Drizzle	Type-safe database access
Auth	Better Auth	Authentication and sessions
Database	DigitalOcean Managed PostgreSQL	Data persistence
Object Storage	Cloudflare R2	Images, media assets
Analytics	Google Tag Manager (Server-Side)	Event tracking via gtag

6. Module Overview¶

By Phase¶

Phase	Module	Description
1	Customer Website	Public storefront with puppy catalog
1	Built-in CMS	Content editing for staff
1	Inventory	Puppy catalog management
1	Media	Photo/video metadata and R2 URL resolution
1	Admin Settings	Store locations, brand config, system settings
1	Rich Text Editor	Lexical-based editor for content fields
1	Auth	User authentication, sessions, role-based access control
2	CRM	Lead tracking and management
2	Analytics	Business intelligence dashboards
2	Price Forecasting	Pricing recommendations
3	SEO AI Agent	Keyword planning, page optimization, AI content/image generation
4	Ecommerce	Full online purchasing + addons
5	Remarketing	Automated follow-up campaigns
6	Social Media	Auto-publish to YouTube, Meta, TikTok

Phase Descriptions¶

Phase 1: Foundation Core customer-facing website with puppy catalog and lead capture. Staff can manage inventory and edit content. Auth module provides user authentication with role-based access control (Sales, Kennel Staff, Photographer, Admin). Media module handles photo/video metadata with R2 storage resolution. Admin Settings manages store locations and brand configuration. Rich Text Editor (Lexical-based) provides consistent editing for all content fields. Reference legacy implementation (BlueSkyPuppies.com) for feature parity.

Phase 2: Operations Intelligence CRM for lead tracking and pipeline management. Analytics dashboards for business visibility. Price forecasting tools to optimize margins.

Phase 3: SEO AI Agent Keyword plan stored in CMS with target keywords per page. AI-generated static images and content for rapid deployment. All pages SEO-optimized with explanations of targeting strategy.

Phase 4: Ecommerce Full online purchasing capability - buy puppies and optional addons directly through the website.

Phase 5: Remarketing Automated follow-up campaigns to re-engage leads who didn't convert. Email sequences, retargeting integration.

Phase 6: Social Media Auto-publish content to YouTube, Meta (Facebook/Instagram), and TikTok. Content pipeline for organic reach and brand building.

7. Data Architecture¶

7.1 Core Entities¶

Entity	Description
Brand	Global settings, branding config
Store	Physical location details
User	Staff/admin accounts with roles
Puppy	Available puppy with details, pricing, photos
Breed	Breed information, care guides
BreedCollection	Groupings of breeds (categories)
Lead	Customer inquiry or reservation
Customer	Buyer profile across interactions
Transaction	Completed purchase/sale
Contract	E-signature documents/agreements
Warranty	Post-sale warranty tracking
Review	Customer testimonials
UGC	User-generated content (photos, stories)
Blog	Articles and content
LandingPage	Marketing landing pages
VirtualLocation	Target cities/geo areas for SEO
Keyword	SEO keyword plan entry
PageSEO	Page-keyword mapping with targeting explanation
AIContent	AI-generated images and content
Media	Photo/video metadata with R2 bucket path resolution

7.2 Entity Relationships¶

erDiagram
    Brand ||--o{ Store : has
    Store ||--o{ Puppy : sells
    Breed ||--o{ Puppy : "is type"
    BreedCollection }o--o{ Breed : groups
    VirtualLocation }o--o{ Store : serves

    Puppy ||--o{ Lead : generates
    Puppy ||--o{ Media : has

    Customer ||--o{ Lead : submits
    Customer ||--o{ Transaction : makes
    Customer ||--o{ Warranty : owns
    Customer ||--o{ Review : writes
    Customer ||--o{ UGC : submits

    Transaction ||--|| Puppy : purchases
    Transaction ||--o{ Contract : requires

    Blog ||--o{ Media : contains
    LandingPage ||--o{ Media : contains
    UGC ||--o{ Media : contains
    AIContent ||--|| Media : generates

    Keyword ||--o{ PageSEO : targets
    PageSEO }o--|| LandingPage : optimizes
    PageSEO }o--|| Blog : optimizes

Text Summary:

Brand (1) ──── (*) Store
Store (1) ──── (*) Puppy
Breed (1) ──── (*) Puppy
BreedCollection (*) ──── (*) Breed
Puppy (1) ──── (*) Lead
Puppy (1) ──── (*) Media
Customer (1) ──── (*) Lead
Customer (1) ──── (*) Transaction
Transaction (1) ──── (1) Puppy
Transaction (1) ──── (*) Contract
Customer (1) ──── (*) Warranty
Customer (1) ──── (*) Review
Customer (1) ──── (*) UGC
VirtualLocation (*) ──── (*) Store
Blog (1) ──── (*) Media
LandingPage (1) ──── (*) Media
UGC (1) ──── (*) Media
AIContent (1) ──── (1) Media
Keyword (1) ──── (*) PageSEO

8. Deployment Architecture¶

8.1 Environments¶

Environment	Purpose	Infrastructure
Development	Local testing	Bun + Docker PostgreSQL
Preview	PR previews	Cloudflare Workers (preview)
Production	Live instances	Cloudflare Workers (3 projects)

8.2 Deployment Model¶

┌─────────────────────────────────────────────────────────────┐
│                     GitHub Repository                        │
│                    (Single Codebase)                         │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ Push to main
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    CI/CD Pipeline                            │
│                   (GitHub Actions)                           │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
│    Brand A        │ │    Brand B        │ │    Brand C        │
│ CF Workers Proj   │ │ CF Workers Proj   │ │ CF Workers Proj   │
│ domain-a.com      │ │ domain-b.com      │ │ domain-c.com      │
│ DO Postgres (A)   │ │ DO Postgres (B)   │ │ DO Postgres (C)   │
│ R2 bucket (A)     │ │ R2 bucket (B)     │ │ R2 bucket (C)     │
└───────────────────┘ └───────────────────┘ └───────────────────┘

8.3 Instance Configuration¶

Each instance configured via environment variables:

DATABASE_URL=        # Instance-specific DO PostgreSQL
R2_BUCKET=           # Instance-specific storage bucket
BRAND_NAME=          # Brand display name
BRAND_COLORS=        # Primary/secondary colors
BRAND_FONTS=         # Font family configuration
DOMAIN=              # Instance domain

9. Technology Stack¶

Note: Use latest stable versions for all software. Keep dependencies updated.

Layer	Technology	Rationale
Language	TypeScript	Type safety, better DX
Framework	Next.js (App Router)	SSR, Server Actions, React ecosystem
Runtime	Bun	Fast, modern JS runtime
Edge Adapter	OpenNext	Deploy Next.js to Cloudflare Workers
Caching	OpenNext R2 Cache	Next.js ISR/caching integration
Query Accelerator	Cloudflare Hyperdrive	PostgreSQL connection pooling, query caching
API Layer	Server Actions	Built-in, type-safe, no extra deps
ORM	Drizzle	Type-safe, lightweight, edge-compatible
Auth	Better Auth	Modern auth, edge-compatible
Database	DigitalOcean Managed PostgreSQL	Reliable, good pricing, predictable
Hosting	Cloudflare Workers	Edge performance, cost-effective
Storage	Cloudflare R2	S3-compatible, no egress fees
Styling	Tailwind CSS	Utility-first, configurable
Components	shadcn/ui	Copy-paste, customizable
CMS	Built-in (custom admin)	Full control, no external dependency
Analytics	Custom dashboards + GTM Server-Side	Built-in dashboards, gtag for event tracking
Email	Resend	Developer-friendly, good deliverability
Payments	Square	Deposits, payments for Phase 3
E-signatures	DocuSeal	Open-source, self-hostable option

10. Decisions¶

D1: Single Codebase with Environment-Based Configuration¶

Status: Accepted Context: Need to deploy same app to 3 brands with different branding/data Decision: One codebase, configure per-instance via environment variables Alternatives: Multi-tenant single deployment, separate codebases Consequences: Simple maintenance, requires careful env var management

D2: Edge-First with Cloudflare Workers¶

Status: Accepted Context: Need fast, global performance at reasonable cost Decision: Deploy to Cloudflare Workers using OpenNext adapter Alternatives: Vercel, AWS, traditional VPS Consequences: Great performance/pricing, some Next.js features may need adaptation

D3: Server Actions for API Layer¶

Status: Accepted Context: Need type-safe communication between React and backend Decision: Use Next.js Server Actions (no separate API/tRPC) Alternatives: tRPC, Hono RPC, REST API Consequences: Simpler architecture, coupled to Next.js

D4: Drizzle ORM with DigitalOcean PostgreSQL¶

Status: Accepted Context: Need reliable database with predictable pricing Decision: Drizzle ORM with DigitalOcean Managed PostgreSQL Alternatives: Neon (serverless), Supabase, Prisma Consequences: Predictable costs, good SLA, slightly more setup than serverless

D5: Built-in CMS¶

Status: Accepted Context: Staff need to edit content without developers Decision: Build content editing into admin dashboard Alternatives: Payload CMS, Sanity, WordPress headless Consequences: Full control, more development work, no external dependency

D6: Phased Delivery¶

Status: Accepted Context: Full ecommerce is complex, need to deliver value quickly Decision: 6-phase delivery starting with catalog + lead gen Alternatives: Build everything at once Consequences: Faster time to value, can learn from each phase

D7: Financing Form Lead Capture¶

Status: Accepted Context: Financing applications are high-intent leads we must capture Decision: Guard financing application form - require name, phone, email before allowing access to start application Alternatives: Direct link to financing provider Consequences: Captures lead info even if they don't complete application

D8: Include Pattern for Relationship Hydration (2026-01-20)¶

Status: Accepted Context: Need flexible data fetching across all modules - sometimes just IDs, sometimes full related objects Decision: All service methods support optional include parameter to hydrate relationships on demand. Base entities store relationship IDs; consumers specify which relationships to hydrate via include options. Alternatives: Always return hydrated objects, always return IDs with separate fetch calls Consequences: Simple backend (one method per operation), consumers control data shape, efficient queries, consistent pattern across all modules

// Example pattern used across all modules
interface PuppyInclude {
  breed?: boolean;
  supplier?: boolean;
  media?: boolean;
}

// Usage
getPuppy(id, { breed: true, media: true })
// Returns puppy with breed and media hydrated, other relations as IDs

11. Open Questions¶

#	Question	Status
1	AI image generation provider (for SEO content)?	Open
2	AI content generation approach (Claude, GPT, etc)?	Open

12. References¶

Vision: VISION-001
Legacy Reference: https://BlueSkyPuppies.com
Legacy Codebase: https://git.apexmediamasters.app/10x/puppies-bsp-flp-hpu-marketing-websites
OpenNext: https://open-next.js.org/
Drizzle: https://orm.drizzle.team/
Better Auth: https://better-auth.com/
shadcn/ui: https://ui.shadcn.com/

Change Log¶

Version	Date	Author	Changes
1.0	2026-01-19	Claude	Initial architecture spec - Approved
1.1	2026-01-20	Claude	Added Media, Admin Settings, and Rich Text Editor modules to Phase 1
1.2	2026-01-20	Claude	Added D8: Include Pattern for Relationship Hydration
1.3	2026-01-20	Claude	Added Auth module to Phase 1