simpleshop_theme/PROGRESS.md

SimpleShop Progress

Single source of truth for project status and task tracking.

Current Status

Working:

• Theme editor with 8 presets, instant switching, full customization
• Image optimization pipeline (AVIF/WebP/JPEG responsive variants)
• Shop pages (home, collections, products, cart, about, contact, error, delivery, privacy, terms)
• Mobile-first design with bottom navigation
• 100% PageSpeed score
• Variant selector with color swatches and size buttons
• Session-based cart with real variant data (add/remove/quantity, cross-tab sync)
• Cart drawer and cart page with hydrated product info
• Stripe Checkout with order persistence and webhook handling
• Admin credentials page with guided Stripe setup flow
• Encrypted settings for API keys and secrets
• Search modal with keyboard shortcut
• Transactional emails (order confirmation, shipping notification)
• Demo content polished and ready for production

Tier 1 MVP complete. Next up: Tier 2 — hosting & deployment.

Roadmap

Tier 1 — MVP (can take real orders and fulfil them)

1. Order management admin — ✅ Complete (02cdc81). Admin UI at /admin/orders with status filter tabs, streamed order table, and detail view showing items, totals, and shipping address.
2. Orders & fulfilment — ✅ Complete. Submit paid orders to Printify, track fulfilment status (submitted → processing → shipped → delivered), webhook-driven status updates with polling fallback, admin UI with submit/refresh actions.
3. Transactional emails — ✅ Complete. Plain text order confirmation (on payment via Stripe webhook) and shipping notification (on dispatch via Printify webhook + polling fallback). OrderNotifier module, 10 tests.
4. Default content pages — ✅ Complete (5a43cfc). Generic ShopLive.Content LiveView handles about + 3 policy pages (delivery, privacy, terms) via live_action. Rich text with list blocks, footer links updated, theme editor preview. 10 tests (575 total).

Tier 2 — Production readiness (can deploy and run reliably)

5. Hosting & deployment — Fly.io or similar deployment config. Release configuration, runtime env setup, health checks. Observability: structured logging, error tracking (Sentry or similar), basic metrics.
6. Litestream / SQLite replication — Litestream for continuous SQLite backup to S3-compatible storage. Point-in-time recovery. Simple sidecar process, no code changes needed, works with vanilla SQLite. For the hosted platform (Tier 5), evaluate Turso (libSQL fork of SQLite) with embedded read replicas via ecto_libsql adapter — gives multi-node reads without a separate replication daemon, but adds a dependency on the libSQL fork.
7. CI pipeline — All checks implemented as mix aliases (mix ci wrapping mix precommit + credo + dialyzer). CI config is a thin wrapper that calls mix ci — portable across GitHub Actions, Forgejo Actions, Woodpecker, or plain SSH. No proprietary CI dependencies. Custom mix tasks for anything project-specific (e.g. mix lighthouse). Oban stays for runtime background jobs, not CI.
8. PageSpeed in CI — Lighthouse CI to catch regressions. Fail the build if score drops below threshold. Protects the current 100% score.
9. End-to-end tests — Wallaby or similar for browser-based tests of critical flows: browse → add to cart → checkout → order confirmation. Covers the full happy path plus key error cases.

Tier 3 — Compliance & quality

10. Accessibility (a11y) — Audit against WCAG 2.1 AA. Focus management, ARIA labels, keyboard navigation, colour contrast. Axe-core integration in CI.
11. Privacy-respecting analytics — Self-hosted, cookie-free analytics. Plausible, Umami, or a lightweight custom solution. No Google Analytics, no third-party tracking. GDPR-friendly by design.
12. AGPL licensing & code hosting — Currently AGPL-3.0. Decide on GitHub vs Codeberg vs self-hosted Forgejo. Set up proper LICENSE file, contribution guidelines, and release process.
13. Security (Paraxial.io) — Runtime application security monitoring for Elixir. Bot detection, rate limiting, vulnerability scanning. Evaluate whether it fits the self-hosted model.

Tier 4 — Growth & content

14. Page editor — Database-driven pages with drag-and-drop sections. Extend the theme system to custom pages beyond the defaults. Replaces the static content pages from Tier 1 with editable versions.
15. Newsletter & email marketing — Email list collection (signup forms). Campaign sending for product launches, sales. Can be simple initially (collect emails, send via Swoosh) or integrate with a service.
16. Product page improvements — Pre-checkout variant validation (verify Printify availability). Cost change monitoring/alerts. Better image gallery (zoom, multiple angles).

Tier 5 — Platform vision

17. Hosted platform — Marketing/brochure site for SimpleShop as a service. Subscribe/sign-up flow. Multi-tenancy with per-tenant databases. Stripe Connect for customer shops (each merchant connects their own Stripe account via OAuth).
18. Migration & export — Let shop owners export their data (products, orders, customers, theme settings). Import from other platforms (Shopify, WooCommerce). Portable data as a selling point for the self-hosted story.
19. Internationalisation (i18n) — Multi-language support via Gettext (already in Phoenix). Currency formatting (ex_cldr already in deps). RTL layout support. Per-shop locale configuration.

---

Feature Areas

Theme System

Status: Complete

• 8 theme presets (Gallery, Studio, Boutique, etc.)
• Three-layer CSS architecture (primitives, attributes, semantic)
• Instant theme switching via CSS custom property injection
• Logo/header image uploads with SVG recoloring
• Self-hosted fonts (10 typefaces, GDPR compliant)
• ETS-cached CSS generation

Image Optimization

Status: Complete

• Oban background job processing
• Responsive <picture> element (AVIF/WebP/JPEG)
• Only generates sizes <= source dimensions
• Disk cache for variants (regenerable from DB)
• mix optimize_images task for mockups
• On-demand JPEG fallback generation
• Product image download pipeline (downloads Printify CDN images, processes through Media pipeline)
  • ImageDownloadWorker downloads and links images to ProductImage
  • PreviewData uses local images for responsive <picture> elements
  • Startup recovery re-enqueues pending downloads
  • mix simpleshop.download_images backfill task

See: docs/plans/image-optimization.md for implementation details

Products & Provider Integration

Status: Complete

• Products context with schemas (c5c06d9)
• Provider abstraction layer
• Printify client integration
• Product/variant/image schemas
• Admin Provider Setup UI (/admin/providers) - connect, test, sync
• ProductSyncWorker with pagination, parallel processing, error recovery
• Slug-based fallback matching for changed provider IDs
• Printify webhook endpoint with HMAC verification (a9c15ea)
  • Note: Printify only supports product:deleted and product:publish:* events (no product:updated)
• Product image download pipeline (1b49b47)
  • Downloads Printify CDN images via ImageDownloadWorker
  • Processes through Media pipeline (WebP conversion, AVIF/WebP variants)
  • Startup recovery and mix simpleshop.download_images backfill
• Variant selector component (880e7a2)
  • Color swatches with hex colors, size buttons
  • Fixed Printify options parsing (Color/Size swap bug)
  • Filters to only published variants (not full catalog)
  • Price updates on variant change
  • Startup recovery for stale sync status

Future Enhancements (post-MVP)

• Pre-checkout variant validation (verify availability before order)
• Cost change monitoring/alerts (warn if Printify cost increased)
• OAuth platform integration (appear in Printify's "Publish to" UI)

Technical Debt

• Mox provider mocking for fulfilment tests (Provider.for_type configurable via app env)

See: docs/plans/products-context.md for implementation details See: docs/plans/printify-integration-research.md for API research & risk analysis

Cart & Checkout

Status: Complete

• Cart drawer component with slide-over panel (1bc08bf)
• Cart page with item list and order summary (1bc08bf)
• Shared CartHook for cross-page cart events (1bc08bf)
• CartPersist JS hook for localStorage backup
• Add-to-cart with flash status feedback
• Cart item links to product pages
• Session-based cart with real variants (1bc08bf)
  • Cart stores {variant_id, qty} tuples in session
  • Hydrates with real product data via Products context
  • Cross-tab sync via PubSub, session persistence via CartController API
• Stripe Checkout integration (ff1bc48, stripity_stripe ~> 3.2)
  • Stripe-hosted Checkout with redirect flow
  • Webhook handler for checkout.session.completed/expired
  • Signature verification via CacheRawBody + construct_event
  • Shipping address collection during checkout
• Order/OrderItem schemas and context (ff1bc48)
  • Order number format: SS-YYMMDD-XXXX
  • Payment status tracking (pending → paid/failed)
  • Price snapshots in OrderItem (protects against changes)
  • Idempotent webhook processing
• Checkout success page with real-time PubSub updates
• Cart clearing after successful payment

See: ROADMAP.md for design notes

Admin Settings & Stripe Setup

Status: Complete

• Encrypted settings infrastructure (eede9bb)
  • encrypted_value column on settings table
  • put_secret/2, get_secret/2, has_secret?/1, secret_hint/1
  • AES-GCM encryption via SECRET_KEY_BASE
  • Secrets loaded into Application env on startup via Secrets.load_all/0
• Guided Stripe setup flow (eede9bb)
  • Stripe.Setup module: connect, disconnect, verify, auto-create webhook
  • Three-state admin UI: not configured, connected (production), connected (dev/localhost)
  • Auto-creates Stripe webhook endpoint on production hosts
  • Dev mode shows Stripe CLI instructions for localhost
  • Manual signing secret input for dev/advanced use
  • API key verification via Stripe.Balance.retrieve/2
• Admin credentials page at /admin/settings (eede9bb)
  • Single Secret key input with "Connect Stripe" button
  • Masked key hints (e.g. sk_test_•••789)
  • Disconnect button clears keys from DB and Application env
  • CSSCache test startup crash fixed (handle_continue pattern)

Orders & Fulfilment

Status: Complete

• Orders context with schemas (ff1bc48)
• Stripe Checkout integration with webhook handling
• Order management admin UI (02cdc81, Roadmap #1)
  • Order list with status filter tabs (all/paid/pending/failed/refunded) and counts
  • Streamed table with row click navigation to detail
  • Order detail with info card, shipping address, line items table with totals
  • Nav link in admin bar, 15 tests
• Printify order submission and fulfilment tracking (Roadmap #2)
  • 9 fulfilment fields on orders (status, provider_order_id, tracking, timestamps)
  • submit_to_provider/1 with idempotent guard, error handling, address mapping
  • refresh_fulfilment_status/1 polls provider for status updates
  • OrderSubmissionWorker (Oban, :checkout queue, max_attempts: 3)
  • FulfilmentStatusWorker (Oban Cron, every 30 mins, :sync queue)
  • Printify order webhook handlers (sent-to-production, shipment:created, shipment:delivered)
  • Stripe webhook auto-enqueues submission after payment confirmed
  • Admin UI: fulfilment badge column, fulfilment card with tracking, submit/refresh buttons
  • Mox provider mocking for test isolation, 33 new tests (555 total)
• Transactional emails (Roadmap #3)
  • OrderNotifier module with plain text emails via Swoosh
  • Order confirmation sent from Stripe webhook after payment + address/email updates
  • Shipping notification sent from Printify shipment webhook + polling fallback
  • Guards for missing customer_email, graceful tracking info handling
  • 10 tests (565 total)

See: docs/plans/products-context.md for schema design

DRY Refactor

Status: Planned

Codebase analysis identified ~380 lines of duplication across LiveViews, templates, and the theme editor. Top priorities: extract ThemeHook for shared mount logic, extract <.shop_layout> wrapper component, consolidate preview assigns. Also: split shop_components.ex (4,400 lines) into focused modules.

See: docs/plans/dry-refactor.md for full analysis and plan

Shop Page Integration Tests

Status: Follow-up

Home, product detail, and cart pages have no LiveView integration tests. Collection and content pages are well-covered (16 and 10 tests respectively). Priority order by logic complexity:

1. Product detail page — variant selection, add-to-cart, gallery, breadcrumb
2. Cart page — cart items, quantity changes, order summary, checkout link
3. Home page — hero section, featured products, category nav (mostly presentational)

Page Editor

Status: Future (Tier 4)

Database-driven pages with drag-and-drop sections. Initially, default content pages (terms, privacy, delivery) will be static templates (Tier 1), later made editable via the page editor.

See: docs/plans/page-builder.md for design

---

Completed Work Reference

Feature	Commit	Notes
Default content pages	5a43cfc	Generic Content LiveView, delivery/privacy/terms pages, 10 tests
Transactional emails	—	Plain text order confirmation + shipping notification, 10 tests
Printify order submission & fulfilment	—	Submit, track, webhooks, polling, admin UI, 33 tests
Order management admin	02cdc81	List/detail views, status filters, 15 tests
Encrypted settings & Stripe setup	eede9bb	Guided setup flow, encrypted secrets, admin credentials page
Stripe checkout & orders	ff1bc48	Stripe Checkout, webhooks, order persistence
Demo content & link fixes	cff2170	Broken links, placeholder text, responsive about image
Cart UI infrastructure	1bc08bf	Cart drawer, cart page, CartHook, CartPersist
Variant selector	880e7a2	Color swatches, size buttons, price updates
Product image download	1b49b47	PageSpeed 100% with local images
Wire shop to real data	c818d03	PreviewData uses Products context
Printify webhooks	a9c15ea	Deletion + publish events
Products context Phase 1	c5c06d9	Schemas, provider abstraction
Admin provider setup UI	5b736b9	Connect, test, sync with pagination
Oban Lifeline plugin	c1e1988	Rescue orphaned jobs
Image optimization	Multiple	Full pipeline complete
Self-hosted fonts	-	10 typefaces, 728KB
Mobile bottom nav	-	Fixed tab bar
PageSpeed 100%	-	All optimizations
Theme presets (8)	-	Gallery, Studio, etc.