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)
• 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
• Demo content polished and ready for production

Next up: Order management and fulfilment (Tier 1)

Roadmap

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

1. Order management admin — Admin UI to view orders, filter by status, see order details and line items. The orders context and schemas exist, this is purely the admin LiveView.
2. Orders & fulfilment — Submit paid orders to Printify via their API. Track fulfilment status (submitted → in production → shipped → delivered). Handle shipping notifications and tracking numbers.
3. Transactional emails — Order confirmation email on payment. Shipping notification with tracking link. Use Swoosh (already configured) with a simple HTML template.
4. Default content pages — Static pages for terms of service, delivery & refunds policy, and privacy policy. Needed for legal compliance before taking real orders. Can be simple markdown-rendered pages initially, upgraded to editable via page editor later.

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

• Add HTTP mocking (Mox/Bypass) for Printify API tests

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: In progress — schemas and checkout done, fulfilment pending (Tier 1)

• Orders context with schemas (ff1bc48)
• Stripe Checkout integration with webhook handling
• Order management admin UI (Roadmap #1)
• Printify order submission (Roadmap #2)
• Fulfilment status tracking (Roadmap #2)
• Transactional emails (Roadmap #3)

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

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
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.