berrypod/docs/PROJECT-OVERVIEW.md

Berrypod: Project Overview

Generated April 2026. For current status, see PROGRESS.md.

Technology Stack

Layer	Technology
Framework	Phoenix 1.8, LiveView 1.1
Language	Elixir 1.19, OTP 28
Database	SQLite (via Ecto + ecto_sqlite3)
HTTP Server	Bandit
Background Jobs	Oban 2.19
Payments	Stripe
Image Processing	Image (VIPS-based)
Asset Build	esbuild
Testing	ExUnit, Mox, LazyHTML

---

Project Structure

lib/
├── berrypod/              # Core business contexts
│   ├── accounts/          # User auth, TOTP
│   ├── products/          # Products, variants, provider connections
│   ├── orders/            # Orders, line items, abandoned carts
│   ├── media/             # Image upload, optimization
│   ├── pages/             # CMS pages, block editor
│   ├── theme/             # CSS generation, presets
│   ├── settings/          # Site configuration
│   ├── analytics/         # Privacy-first tracking
│   ├── providers/         # Printify/Printful abstraction
│   ├── shipping/          # Rates, country detection
│   ├── newsletter/        # Subscribers, campaigns
│   ├── reviews/           # Product reviews
│   ├── activity_log/      # Event logging
│   └── redirects/         # URL redirects, 404 tracking
└── berrypod_web/          # Web layer
    ├── live/admin/        # Admin LiveViews
    ├── live/shop/         # Shop LiveViews
    ├── components/        # UI components
    ├── controllers/       # HTTP controllers
    └── plugs/             # Request middleware

---

Core Business Contexts

Products (lib/berrypod/products/)

• Products synced from POD providers (Printify/Printful)
• Variants with pricing, cost, availability tracking
• Image optimization pipeline (WebP conversion, AVIF/JPEG variants at 400/800/1200px)
• Denormalized fields: cheapest_price, in_stock, on_sale
• Status flow: draft → active → archived → discontinued

Orders (lib/berrypod/orders/)

• Order numbers: SS-YYMMDD-XXXX format
• Payment tracking: pending → paid → failed → refunded
• Fulfilment: unfulfilled → submitted → processing → shipped → delivered
• Abandoned cart recovery (24hr inactivity triggers)
• Stripe session/payment intent tracking

Media & Images (lib/berrypod/media/, lib/berrypod/images/)

• BLOB storage in SQLite
• Lossless WebP conversion on upload (26-41% smaller)
• Dominant color extraction for header images
• Async variant generation via Oban workers
• Usage tracking across products, pages, themes

Pages (lib/berrypod/pages/)

• 14 system pages + unlimited custom CMS pages
• Block-based editor with 26 block types (hero, text, gallery, grid, testimonials, etc.)
• ETS caching with DB fallback
• Auto-redirect creation when URLs change
• Navigation menu integration

Theme (lib/berrypod/theme/)

• 3-layer CSS architecture:
  1. Primitives (CSS custom properties)
  2. Attributes (theme-specific rules)
  3. Semantic (component styles)
• 8 presets: Gallery, Studio, Boutique, etc.
• Instant switching via CSS variable injection (no reload)
• WCAG contrast checking

Analytics (lib/berrypod/analytics/)

• Privacy-first: no cookies, no personal data, GDPR-friendly
• Visitor hashing with daily-rotating salt
• Event types: pageview, product_view, add_to_cart, checkout_start, purchase
• Metrics: unique visitors, bounce rate, top pages, sources, countries, devices
• E-commerce funnel tracking with revenue

Providers (lib/berrypod/providers/)

• Behaviour-based abstraction layer
• Printify: 800+ products from 90+ print providers
• Printful: In-house production with warehousing
• Operations: test connection, fetch products, submit orders, track status, fetch shipping rates

Reviews (lib/berrypod/reviews/)

• 1-5 star ratings with text + images (up to 3)
• Verified purchase badge
• Moderation workflow: pending → approved/rejected
• Rating denormalization to products

Newsletter (lib/berrypod/newsletter/)

• Double opt-in with confirmation emails
• Plain text only (no tracking pixels)
• Campaign scheduling and bulk sending
• Global suppression list

---

Database Schema (26 Schemas)

Core entities:

• User, UserToken - Authentication
• Product, ProductImage, ProductVariant - Catalog
• ProviderConnection - POD credentials (encrypted)
• Order, OrderItem, AbandonedCart - Commerce
• Page, NavItem, SocialLink - Content
• Image, FaviconVariant - Media
• ShippingRate - Rates by country/provider
• Review - Product reviews
• Newsletter.Subscriber, Newsletter.Campaign - Email
• Analytics.Event - Tracking
• ActivityLog.Entry - System events
• Redirects.Redirect, BrokenUrl, DeadLink - URLs
• Setting - Configuration (JSON, encrypted)

---

Background Jobs (Oban)

Scheduled (cron)

Schedule	Worker	Purpose
Every 30min	FulfilmentStatusWorker	Poll provider for order updates
Every 6hr	ScheduledSyncWorker	Product sync
Daily 3am	RetentionWorker	Delete old analytics
Daily 3:30am	DeadLinkCheckerWorker	Scan for broken links
Every 5min	ScheduledCampaignWorker	Send scheduled campaigns

On-demand

• ProductSyncWorker - Sync products from provider
• ImageDownloadWorker - Download product images
• OptimizeWorker - Generate image variants
• OrderSubmissionWorker - Submit to fulfilment
• ReviewRequestWorker - Send review request after delivery
• CampaignSendWorker - Newsletter campaigns

---

Web Layer

Admin LiveViews (/admin/*)

• Dashboard, Analytics, Orders, Products, Providers
• Settings, Media, Pages, Newsletter, Reviews
• Activity log, Backup, Redirects

Shop LiveViews (public)

• Home, Collections, Products, Cart, Checkout
• Contact (with order lookup), Search, Review forms
• Custom CMS pages via catch-all route /:slug

Key Routes

Path	Purpose
/	Shop home
/collections/:slug	Category browsing
/products/:id	Product detail
/cart	Shopping cart
/admin	Admin dashboard
/admin/orders	Order management
/admin/pages	Page editor
/admin/media	Media library
/admin/analytics	Analytics dashboard
/admin/theme	Theme editor
/:slug	Custom pages (catch-all)

---

Asset Pipeline

No Tailwind - Hand-written CSS with:

• @layer for cascade organization
• Native CSS nesting
• oklch() color function
• CSS custom properties for theming

Bundles:

• berrypod - Main JS
• berrypod_shop_css - Storefront styles
• berrypod_admin_css - Admin styles
• berrypod_theme_css - Dynamic theme CSS

---

Key Features

For Shop Owners

• Product sync from Printify/Printful with image optimization
• Block-based CMS page builder (26+ block types)
• Live theme editor with 8 presets
• Privacy-first analytics (no cookies, GDPR-friendly)
• Order management with fulfilment tracking
• Abandoned cart recovery emails
• Newsletter with double opt-in
• Product review system with moderation
• Activity log for system events

For Customers

• Product browsing with collections/filters
• Session-based shopping cart
• Stripe checkout
• Order lookup via email
• Review submissions

---

Security & Performance

Security

• Vault encryption for secrets
• CSRF protection, secure headers
• TOTP two-factor auth for admin
• Webhook signature verification (Stripe, Printify, Printful)

Performance

• ETS caching (settings, theme CSS, pages, redirects)
• Streams for LiveView collections
• Batch analytics flushing
• Image variants with lazy generation
• Pagination throughout

---

Outstanding Work

Active Plans (Ready to Implement)

1. Profit-Aware Pricing & Sales (plan) ~16h

Task	Est	Status
Fix Printful cost sync (catalog API cross-reference)	45m	planned
Cost snapshot on orders (unit_cost, gross_profit)	1.5h	planned
Exact Stripe fees from Balance Transaction API	45m	planned
Tax toggle + Stripe Tax integration	1.5h	planned
Admin profit dashboard (margins, P&L)	3h	planned
Profit-aware price editor (live margin display)	2h	planned
Sales & promotions (%, fixed, scoped, scheduled)	3h	planned
Margin guard (prevent profit-killing discounts)	1h	planned
Announcement bar for active sales	1.5h	planned

2. Competitive Gaps - Phase 1: Core Commerce (plan) ~17h

Task	Est	Status
Customer authentication schema	2h	planned
Customer auth flows (login, register, reset)	3h	planned
Link orders to customers	1.5h	planned
Customer account dashboard	2h	planned
Saved addresses	1.5h	planned
Guest checkout linking	1h	planned
PayPal SDK integration	2h	planned
PayPal checkout flow	3h	planned
PayPal webhooks	1.5h	planned

3. Competitive Gaps - Phase 2: Retention & Growth ~14h

Task	Est	Status
Returns schema	1.5h	planned
Return request flow	2h	planned
Return admin	2h	planned
Return policy settings	1h	planned
Email sequence schema	2h	planned
Sequence triggers & sending	3h	planned
Sequence admin	2h	planned
Customer data export (GDPR)	1.5h	planned
Customer data deletion (GDPR)	2h	planned

4. Competitive Gaps - Phase 3: Scale ~7h

Task	Est	Status
Blog post type	3h	planned
Staff accounts & RBAC	4h	planned

5. SEO Enhancements (plan) ~21h

Task	Est	Status
Per-page noindex/nofollow + meta descriptions	2h	planned
Enhanced Organization schema	2h	planned
Image sitemap entries	1h	planned
SEO preview panel (Google + social cards)	4h	planned
Focus keyword & SEO score/checklist	4h	planned
FAQ block with FAQPage schema	2h	planned
Google Search Console OAuth integration	6h	planned

6. Draft-then-Publish Workflow (plan) ~31h

Phase	Description	Est
0	Site-level publishing (coming soon → live)	1.5h
1	Page versions and drafts (auto-save, publish/discard)	7h
2	Theme drafts	4h
3	Settings drafts	4h
4	Version history and rollback (diff view, history panel)	5.5h
5	Image soft delete and trash (usage check, restore, auto-purge)	4.5h
6	Polish and pruning (conflict handling, retention worker)	4.25h

Key features: auto-save drafts, explicit publish, version history with rollback, image trash/recycle bin, tiered version retention.

---

Platform/Business Items

Task	Status
Platform/marketing site (brochure, pricing, sign-up)	planned
Separation of platform site vs AGPL open source core	planned

---

Production Hardening

Item	Description
Litestream / SQLite replication	Continuous backup to S3, point-in-time recovery
End-to-end & accessibility tests	Wallaby browser tests, WCAG 2.1 AA
Security monitoring	Paraxial.io for runtime security, bot detection, rate limiting
AGPL licensing	LICENSE file, contribution guidelines, release process

---

Future Enhancements

Feature	Description
Multiple print providers	Route products to different providers based on cost/type
Product page improvements	Pre-checkout validation, cost monitoring, better gallery
Editable email templates	Admin UI for customizing transactional emails
Hosted platform infrastructure	Multi-tenancy, OAuth connect for providers/payments
Migration & export	Shopify/WooCommerce import, data export
Internationalisation	Multi-language (Gettext), currency formatting, RTL

---

Summary by Priority

High priority (core commerce):

1. Customer accounts + PayPal (~17h)
2. Profit-aware pricing + sales (~16h)

Medium priority (polish): 3. SEO enhancements (~21h) 4. Draft-then-publish workflow (~31h) 5. Returns system (~6.5h) 6. Email sequences (~7h)

Lower priority (scale): 7. Blog post type (3h) 8. Staff accounts & RBAC (4h) 9. Platform site (TBD)

Total estimated remaining: ~100-120h of planned work, plus the larger platform vision items.

---

Design Philosophy

1. "One theme, infinite variations" — one solid foundation with curated customisation
2. Constrained creativity — limit choices to prevent poor design outcomes
3. No professional photography required — works with product mockups
4. Mobile-first — all features work on touch devices
5. Ethical design — no dark patterns or fake urgency
6. Privacy-first — cookie-free analytics, GDPR-compliant cart recovery, no tracking pixels