add competitive gap analysis document

PROGRESS.md

@@ -194,3 +194,4 @@ All plans in [docs/plans/](docs/plans/). Completed plans are kept as architectur
 | [draft-publish-workflow.md](docs/plans/draft-publish-workflow.md) | Planned |
 | [editor-reorganisation.md](docs/plans/editor-reorganisation.md) | Planned |
 | [seo-enhancements.md](docs/plans/seo-enhancements.md) | Planned |
+| [competitive-gap-analysis.md](docs/plans/competitive-gap-analysis.md) | Reference |

docs/plans/competitive-gap-analysis.md

@@ -0,0 +1,432 @@
+# Competitive Gap Analysis
+
+Status: Reference
+
+## Overview
+
+Comprehensive audit of Berrypod against e-commerce competitors (Shopify, Squarespace, WooCommerce) and POD platforms (Spring/Teespring, Redbubble). Conducted March 2026.
+
+## Gap Analysis: Berrypod vs Competitors
+
+### Critical Gaps (blocking competitiveness)
+
+| Gap | Notes |
+|-----|-------|
+| **Customer accounts** | No customer login, order history, saved addresses. Returning customers can't see past orders without contacting support. |
+| **Discount/coupon codes** | Essential e-commerce feature. Planned in profit-aware-pricing but not done. |
+| **Returns management** | No return requests, RMA tracking, or refund workflow. |
+| **PayPal** | Only Stripe available. PayPal is still expected by ~30% of buyers. |
+| **Product reviews** | Block exists for display but no submission or moderation system. |
+
+### High Priority (expected by competitors)
+
+| Gap | Notes |
+|-----|-------|
+| **Stock level display** | Only boolean in_stock. No "only 3 left" urgency. |
+| **Buy-now-pay-later** | No Klarna/Afterpay. Critical for UK/EU/AU conversions. |
+| **Email sequences** | Only single campaigns. No welcome flow, browse abandon, post-purchase. |
+| **Multiple active providers** | Can connect both Printify + Printful but no routing logic between them. |
+| **Customer data export/deletion** | GDPR right-to-erasure not fully implemented. |
+
+### Medium Priority (differentiators)
+
+| Gap | Notes |
+|-----|-------|
+| **Blog** | Page builder exists but no publish date, categories, author. |
+| **Social selling** | No Instagram Shop, TikTok Shop, Facebook catalog feeds. |
+| **Customer insights** | Basic analytics but no cohort analysis, LTV, repeat rate. |
+| **Abandoned browse recovery** | Only cart abandonment emails, not "you looked at X" emails. |
+
+---
+
+## Detailed Category Analysis
+
+### 1. Customer Experience Features
+
+#### What Exists
+- **Product Search**: FTS5 full-text search with live modal, keyboard navigation, ARIA support
+- **Product Filtering**: By collection/category with live filtering UI
+- **Product Pages**: Detailed product pages with image gallery per colour, variant selector
+- **Related Products**: Shown on product pages (configurable toggle)
+- **Shopping Cart**: Session-based cart with cross-tab sync, cart drawer + full page, quantity controls
+- **Checkout**: Stripe Checkout with order confirmation, GDPR-compliant abandoned cart recovery
+- **Order Lookup**: Contact page with order status lookup functionality
+- **Contact Form**: Contact form for inquiries
+- **Mobile-Optimized**: Mobile bottom navigation, responsive design, mobile checkout
+
+#### What's Missing
+| Feature | Priority | Notes |
+|---------|----------|-------|
+| Customer Accounts/Login | Critical | Only admin accounts exist. No customer authentication, order history, saved addresses |
+| Wishlists/Favorites | Medium | No wishlist system for customers |
+| Product Reviews/Ratings | Critical | Block type exists for display only; no review submission/moderation system |
+| Customer Q&A | Medium | No product questions feature |
+| Review Schema/Social Proof | Medium | Reviews block is placeholder; needs backend |
+| Account Dashboard | Critical | No `/my-account` or customer profile management |
+| Saved Addresses | Medium | No address book for returning customers |
+| Subscription Orders | Low | No recurring/subscription products |
+
+---
+
+### 2. Product Features
+
+#### What Exists
+- **Product Variants**: Full support (colors/sizes/materials) with price + cost per variant
+- **Product Categorization**: Collections (categories) with filtering
+- **Variant Selection UI**: Radio buttons for options with image filtering per variant
+- **Stock Status**: `in_stock` boolean field; stock filtering in admin
+- **Multi-image Gallery**: Per-product with per-color filtering
+- **Provider Sync**: Automatic sync from Printify + Printful with mockup enrichment
+- **Product Search**: Full-text search indexing
+- **Related Products Block**: Manual/automatic related product display
+
+#### What's Missing
+| Feature | Priority | Notes |
+|---------|----------|-------|
+| Inventory Tracking | High | No real-time inventory per variant; just in_stock boolean. Doesn't sync provider inventory limits. |
+| SKU Management | Medium | No SKU field visible in product data |
+| Bundles | Medium | No bundle/combo products |
+| Upsells | Medium | No "frequently bought together" or upsell UI |
+| Cross-Sells | Medium | No automatic cross-sell recommendations |
+| AI Product Recommendations | Low | No ML-based "you might like" |
+| Bulk Import | Medium | Only sync from Printify/Printful; no CSV import |
+| Dynamic Pricing Rules | Low | No conditional pricing (volume, time-based) |
+
+---
+
+### 3. Checkout & Payments
+
+#### What Exists
+- **Stripe Checkout**: Full integration with order persistence, webhook handling
+- **Payment Methods**: Stripe Checkout supports cards, Apple Pay, Google Pay (handled by Stripe)
+- **Shipping Integration**: Carrier rates synced from Printify/Printful per country
+- **Order Confirmation**: Email + contact page lookup
+- **GDPR Cart Recovery**: Single abandoned cart recovery email
+- **Session Cart**: Client-side cart state
+- **Currency Support**: Multi-currency (shops set currency in settings, shipping rates by country)
+
+#### What's Missing
+| Feature | Priority | Notes |
+|---------|----------|-------|
+| PayPal/Venmo | Critical | Only Stripe available; PayPal is market standard |
+| Klarna/Afterpay | High | Buy-now-pay-later crucial for conversions (esp. UK/EU/AU) |
+| Local Payment Methods | Medium | iDEAL, SEPA, Alipay, WeChat, etc. depend on Stripe region |
+| Discount/Coupon Codes | Critical | Planned in profit-aware-pricing; currently not implemented |
+| Gift Cards | Medium | No gift card system |
+| Promo Codes | Critical | Planned (as transparent sales, not codes) |
+| Cart Recovery Campaign | Medium | Only 1 automated email; no multi-email sequences |
+| Upsells at Checkout | Low | No checkout upsell/gift suggestion |
+| Subscription/Recurring | Low | Not implemented |
+
+---
+
+### 4. Marketing & Growth
+
+#### What Exists
+- **Newsletter Signup**: Forms on shop pages, double opt-in, GDPR-compliant
+- **Newsletter Campaign Sending**: Admin can send campaigns to subscribers
+- **Email List Export**: CSV export of subscribers (for GDPR compliance)
+- **Social Links**: Configurable social media links (Instagram, Twitter, Facebook, TikTok, etc.)
+- **Analytics**: Privacy-first pageview tracking, product view, add-to-cart, checkout-start, purchase events
+- **Referrer Tracking**: Source attribution (direct, organic, social platforms)
+- **Analytics Dashboard**: Comparison mode, filtering, CSV export
+- **SEO**: Complete meta tags, OG/Twitter cards, JSON-LD, XML sitemap, canonical URLs, robots.txt
+- **Related Products**: Auto-display on product pages
+- **Trust Badges Block**: Configurable trust/badge display
+
+#### What's Missing
+| Feature | Priority | Notes |
+|---------|----------|-------|
+| Countdown Timers | Medium | No urgency indicators (sale ending, stock limited) |
+| Stock Level Display | High | Can show in_stock boolean, but no "only 3 left" |
+| Referral Program | Low | No built-in affiliate/referral system |
+| Email Sequences | High | No marketing automation (welcome, browse abandon, post-purchase) |
+| SMS Marketing | Low | No SMS integration |
+| Influencer Codes | Low | No influencer/code tracking |
+| Pop-ups/Overlays | Low | No popup or exit-intent system |
+| Blog/Content Hub | Medium | Page builder exists but no blog datetime, categories, author |
+| Lookbooks | Medium | Manual pages only; no lookbook block type |
+| Live Chat | Low | No built-in live chat |
+| Social Selling (Instagram Shop, TikTok Shop) | Medium | No direct marketplace integration |
+| Email Segmentation | Medium | All subscribers get same campaign |
+| Abandoned Browse Recovery | Medium | Only cart abandoned; no browse-without-purchase emails |
+| Post-Purchase Email Sequence | Medium | Only order confirmation; no follow-up sequence |
+| Product Feed (Facebook, Pinterest) | Low | No auto-generated product feeds |
+
+---
+
+### 5. Analytics & Reporting
+
+#### What Exists
+- **Privacy-First Pageview Tracking**: Cookie-free, GDPR-friendly, no personal data
+- **E-commerce Events**: product_view, add_to_cart, checkout_start, purchase (with revenue)
+- **Conversion Funnel**: All events tracked and reportable
+- **Referrer Attribution**: Social platform detection, UTM tracking
+- **CSV Export**: Analytics data export for external analysis
+- **Device/OS Tracking**: Browser, OS, screen size classification
+- **Country Detection**: GeoIP-based country attribution
+- **Comparison Mode**: Compare time periods
+- **Real-time Updates**: Dashboard updates as events occur
+- **Sales Reports**: Orders with status, dates, shipping addresses
+
+#### What's Missing
+| Feature | Priority | Notes |
+|---------|----------|-------|
+| Customer Insights | Medium | No cohort analysis, repeat rate, LTV |
+| Product Performance | Medium | No top-sellers, returns rate, profitability per product |
+| Traffic Sources Breakdown | Low | Basic referrer; no paid ads tracking (Google Ads, Facebook Ads) |
+| Profit Reporting | High | Planned (profit per order, margin analysis, P&L dashboard) |
+| Inventory Analytics | Low | No stock movement, sellthrough rate |
+| Forecasting | Low | No predictive analytics |
+| Heatmaps/Session Replay | Low | Privacy-first philosophy doesn't support this |
+| Attribution Modeling | Low | Linear attribution only; no multi-touch |
+
+---
+
+### 6. Multi-Channel & Operations
+
+#### What Exists
+- **Provider Sync**: Printify + Printful (order submission, tracking, sync)
+- **Shipping Rates Sync**: Carrier rates per country synced from providers
+- **Order Status Tracking**: Provider status → Berrypod (unfulfilled → shipped → delivered)
+- **Webhooks**: Stripe + provider webhooks for real-time updates
+- **Fulfillment Timeline**: Order timeline with submitted/shipped/delivered dates
+- **Activity Log**: Global event feed, order-specific timeline, contextual retry
+
+#### What's Missing
+| Feature | Priority | Notes |
+|---------|----------|-------|
+| Multiple Active Providers | High | Can only connect one Printify + one Printful; no multi-provider routing |
+| Marketplace Integration | Medium | No Etsy, Amazon Handmade, TikTok Shop, Shopee connectors |
+| Social Selling (Native) | Low | Facebook/Instagram shop feeds not auto-synced |
+| Inventory Across Providers | High | No centralized inventory limit (each provider independent) |
+| Tax Management | High | Planned (Stripe Tax toggle, VAT registration) |
+| Returns Management | Critical | No return request UI, return authorization, RMA tracking |
+| Multi-currency Pricing | Medium | One currency per order; no dynamic pricing by country |
+| International Shipping | Medium | Rates supported; no customs, duties, labels |
+| Bulk Order Export | Low | No Shopify-style bulk action export |
+
+---
+
+### 7. Content & Pages
+
+#### What Exists
+- **Page Builder**: 26 block types (hero, product grid, content, newsletter, etc.)
+- **Custom CMS Pages**: Editable at any URL (/{slug})
+- **Auto-Generated Pages**: About, Contact, Legal (privacy/terms/delivery) auto-generated from settings
+- **Blocks Available**: Hero banner, Featured products, Product grid, Related products, Collection navigation, Newsletter signup, Social links, Trust badges, Reviews section, Content body, Info cards, Video embed, FAQ section, Contact form, Order tracking, and more
+- **Page SEO**: Meta title, description per page
+- **Breadcrumb Schema**: Dynamic breadcrumbs with schema
+
+#### What's Missing
+| Feature | Priority | Notes |
+|---------|----------|-------|
+| Blog with Dates | Medium | No blog post type with publish date, author, categories |
+| Knowledge Base | Low | No FAQ with search/filtering |
+| Lookbooks | Medium | No dedicated lookbook block with multiple images + text |
+| Video Hosting | Low | Embed only (YouTube, Vimeo); no native video |
+| Rich Media Gallery | Low | Limited to static images; no video galleries |
+| Customer Reviews Display | Medium | Review block exists but no backend (reviews not submittable) |
+| Comments/Discussions | Low | No user comments on pages/products |
+| Versioning/Audit Trail | Low | No page revision history |
+| Schedule Publishing | Low | All pages live immediately |
+
+---
+
+### 8. Mobile & Accessibility
+
+#### What Exists
+- **Mobile-First Design**: All shop pages responsive
+- **Mobile Bottom Navigation**: Thumb-friendly mobile nav
+- **Mobile Drawer**: Mobile menu with collections
+- **Mobile Checkout**: Full Stripe Checkout support
+- **Responsive Images**: AVIF/WebP/JPEG with responsive srcset
+- **Touch-Friendly**: Large touch targets, spacing
+- **PWA Basics**: Web manifest, viewport meta, favicon variants (PNG + SVG)
+- **No-JS Support**: Core flows work without JavaScript (forms, navigation)
+- **WCAG Compliance**: Input styling (WCAG AA/AAA), ARIA labels, semantic HTML
+- **Mobile PageSpeed**: 99-100 Lighthouse mobile score
+- **Mobile Analytics**: Screen size classification
+
+#### What's Missing
+| Feature | Priority | Notes |
+|---------|----------|-------|
+| PWA Install Prompt | Low | Manifest exists; no install banner |
+| Offline Mode | Low | No offline browsing or offline cart persistence |
+| Mobile App | Low | Web-only; no native iOS/Android app |
+| One-Click Checkout | Medium | Stripe Checkout handles; no express checkout UX |
+| Mobile-Specific Features | Low | No mobile-exclusive features (AR try-on, location services) |
+
+---
+
+### 9. Security, Compliance & Data
+
+#### What Exists
+- **User Authentication**: Email + password with bcrypt hashing
+- **2FA/TOTP**: Full TOTP support with backup codes (encrypted at rest)
+- **HTTPS**: Force SSL redirect, secure cookies
+- **GDPR Compliance**: Privacy policy auto-gen, abandoned cart compliance, unsubscribe handling
+- **Data Isolation**: Per-shop data (single-tenancy at app level)
+- **Password Reset**: Email-based token links
+- **Email Verification**: Confirmed_at timestamp
+- **Encrypted Secrets**: Payment/provider keys encrypted with Vault
+- **Activity Logging**: All admin actions logged
+
+#### What's Missing
+| Feature | Priority | Notes |
+|---------|----------|-------|
+| Customer Data Export | Medium | No GDPR export for customers (only newsletter subscribers) |
+| Data Deletion Right | High | No automated customer data purge |
+| IP Whitelisting | Low | No IP access restrictions |
+| Rate Limiting | Medium | Basic rate limiting exists; could be stronger |
+| Audit Trail Export | Low | Activity log exists; no export for compliance |
+| API Keys/Webhooks | Medium | Stripe webhooks only; no custom API |
+| Role-Based Access (RBAC) | Low | Single admin role; no staff accounts with limited permissions |
+| Backup/Recovery | High | No documented backup strategy (Litestream planned) |
+
+---
+
+### 10. Operations & Business Tools
+
+#### What Exists
+- **Order Management**: Full order list, detail page, status tracking
+- **Activity Log**: System-wide event feed, per-order timeline, contextual retry buttons
+- **Order Lookup**: Customers can find orders by order number + email
+- **Abandoned Cart Recovery**: GDPR-compliant single recovery email
+- **Inventory Tracking**: in_stock boolean field per product
+- **Abandoned Cart Log**: Tracked in abandoned_cart table
+- **Email Suppression**: Auto-suppress bounces/unsubscribes
+- **Contextual Action Retry**: Resend webhooks, retry provider submission
+
+#### What's Missing
+| Feature | Priority | Notes |
+|---------|----------|-------|
+| Profit Dashboard | High | Planned: per-product margin, per-order P&L, overall P&L |
+| Minimum Margin Alerts | High | Planned: prevent pricing/discounts below threshold |
+| Cost Tracking | High | Variant costs synced; cost snapshots at order (planned) |
+| Sales Reports | Medium | Basic order list; no time-series sales analysis |
+| Expense Tracking | Low | No expense logging |
+| Tax Reporting | Medium | Basic VAT toggle; no tax-specific reporting |
+| Inventory Alerts | Medium | No low-stock alerts |
+| Multi-User Accounts | Low | Only single owner; no staff accounts |
+| Permissions/Roles | Low | No role-based access control |
+| Staff Activity Audit | Low | Activity log logs everything; no "who did what" breakdown |
+| Bulk Refunds | Medium | Manual refund only (via provider dashboard) |
+| Return Requests | Critical | No return authorization, no RMA tracking |
+
+---
+
+### 11. Internationalization & Localization
+
+#### What Exists
+- **Multi-Currency Shipping**: Rates calculated per customer country
+- **Currency Field**: Order currency stored (GBP default)
+- **Exchange Rate Caching**: GBP-to-currency rates cached daily
+- **Country Detection**: GeoIP + Accept-Language header
+- **Shipping Rates by Country**: Provider rates per country code
+
+#### What's Missing
+| Feature | Priority | Notes |
+|---------|----------|-------|
+| Multi-Language (i18n) | Medium | Gettext infrastructure exists; only English implemented |
+| Translated Shipping Info | Low | No country-specific shipping copy |
+| RTL Layout Support | Low | No RTL CSS (planned for future) |
+| Regional Currencies | Medium | Show prices in customer currency (on product pages) |
+| Locale-Aware Formatting | Low | ex_money dependency exists but only for GBP |
+
+---
+
+## Priority Gap Matrix
+
+### Critical (Blocks Competitiveness)
+1. **Customer Accounts** — No way for returning customers to log in or see order history
+2. **Discount/Coupon Codes** — Essential e-commerce feature; planned in profit-aware-pricing
+3. **Returns Management** — No RMA, return requests, or process
+4. **PayPal** — Only Stripe available; PayPal expected by ~30% of buyers
+5. **Product Reviews** — Block exists but no submission/moderation
+
+### High (Expected by Competitors)
+1. **Cost/Profit Visibility** — Planned in profit-aware-pricing
+2. **Tax Management** — Planned (Stripe Tax integration)
+3. **Multiple Print Providers** (active) — Can only use 1 Printify + 1 Printful
+4. **Stock Level Display** — Only boolean; no "3 left" messaging
+5. **Email Marketing Sequences** — Only single campaigns
+6. **Customer Data Export/Deletion** — GDPR right not fully implemented
+7. **Buy-Now-Pay-Later** — No Klarna/Afterpay
+
+### Medium (Nice-to-Have, Differentiators)
+1. **Social Selling** (Instagram, TikTok Shop) — Manual linking only
+2. **Blog/Content Hub** — Pages exist; no datetime, categories
+3. **Lookbooks** — No dedicated block type
+4. **Abandoned Browse Recovery** — Only cart, not product browsing
+5. **Customer Insights/Cohorts** — Analytics dashboard basic only
+6. **Referral Program** — No affiliate system
+7. **Staff Accounts/RBAC** — No team access
+
+### Low (Niche/Advanced)
+1. **PWA Install Prompt** — Infrastructure exists, no user-facing install
+2. **Marketplace Integration** (Etsy, Amazon) — No connectors planned
+3. **SMS Marketing** — Not in roadmap
+4. **Live Chat** — Not in roadmap
+5. **Heatmaps/Session Replay** — Conflicts with privacy-first philosophy
+
+---
+
+## Key Strengths (vs Competitors)
+
+1. **Privacy-First by Default**: Cookie-free analytics, GDPR-compliant, no tracking pixels
+2. **Hand-Optimized CSS**: 12 KB gzipped shop CSS (vs Tailwind-heavy Shopify)
+3. **Page Builder with 26 Blocks**: Comparable to Webflow/Wix, built in-house
+4. **Unified On-Site Editing**: Edit theme/pages live on the real shop (not preview)
+5. **Open Source (AGPL)**: Self-hostable, no vendor lock-in
+6. **Fast**: 99-100 PageSpeed mobile, no-JS support
+7. **Provider Agnostic**: Mockup enrichment, shipping sync, order tracking for both major POD providers
+8. **Legal Page Auto-Generation**: Privacy policy, terms, delivery auto-generated from settings
+
+---
+
+## Recommended Prioritization
+
+### Phase 1 (Core Commerce Gaps)
+- [ ] Customer accounts/login + order history (blocks all repeat customer features)
+- [ ] Discount/coupon codes or transparent sales system (planned in profit-aware-pricing)
+- [ ] Expand payment methods (PayPal, at minimum; Klarna/Afterpay for key markets)
+- [ ] Product review system (backend + moderation)
+- [ ] Stock level display ("only 3 left" messaging)
+
+### Phase 2 (Retention & Growth)
+- [ ] Email marketing sequences (welcome, browse abandon, post-purchase)
+- [ ] Returns/RMA management
+- [ ] Multiple active print providers with routing logic
+- [ ] Profit dashboard + margin warnings
+- [ ] Customer data export/deletion (full GDPR compliance)
+
+### Phase 3 (Scale)
+- [ ] Social selling integrations (Instagram Shop, TikTok Shop)
+- [ ] Blog with categories, dates, author
+- [ ] Staff accounts + role-based access
+- [ ] Litestream backup + security hardening
+
+---
+
+## Planned Items Already in Roadmap
+
+| Feature | Plan File | Status |
+|---------|-----------|--------|
+| Profit-aware pricing & sales | profit-aware-pricing.md | Planned |
+| Tax management (Stripe Tax) | profit-aware-pricing.md | Planned |
+| SEO enhancements | seo-enhancements.md | Planned |
+| Multiple print providers | ROADMAP.md | Planned |
+| Newsletter sequences | ROADMAP.md | Planned |
+| Product reviews | ROADMAP.md | Planned |
+| Security hardening | security-hardening.md | Planned |
+| Litestream backup | ROADMAP.md | Planned |
+| E2E + a11y tests | ROADMAP.md | Planned |
+
+---
+
+## Conclusion
+
+Berrypod has **solid foundational e-commerce** (shop, cart, checkout, admin) and **exceptional technical execution** (performance, CSS architecture, privacy). However, it's missing **critical customer features** (accounts, reviews, returns) and **business tools** (profit tracking, advanced analytics) that are table stakes in the POD space. The planned roadmap addresses most high-priority gaps.
+
+The biggest unlock is **customer accounts** since it enables wishlists, reviews, order history, and saved addresses.