jamey/berrypod
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

tidy docs: condense progress, trim readme, mark plan statuses

Browse Source 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
jamey
2026-03-01 17:15:18 +00:00
parent 580a7203c9
commit edef628214
15 changed files with 263 additions and 810 deletions
Download Patch File Download Diff File Expand all files Collapse all files

243
README.md
View File

@@ -1,201 +1,126 @@
# Berrypod
A beautiful, customisable e-commerce storefront built with Phoenix LiveView. Designed for print-on-demand sellers who want professional shops without design expertise.
A customisable e-commerce storefront for print-on-demand sellers, built with Phoenix LiveView. Professional shops without design expertise, privacy-respecting by default, fully self-hostable.
## Features
### The Shop
A complete storefront with all the pages you need:
- **Home** - Hero banner, category navigation, featured products, testimonials
- **Products** - Grid layout with hover effects and filtering
- **Product Detail** - Image gallery, variants, reviews, related products
- **Cart** - Full shopping cart with order summary
- **Checkout** - Stripe-hosted checkout with order confirmation
- **About** - Rich content with your brand story
- **Contact** - Contact form with business details
- **Error pages** - Themed 404/500 pages
### Shop
Complete storefront with all the pages you need:
- **Home** — hero banner, category navigation, featured products, newsletter
- **Products** — grid layout with hover effects, sorting, filtering by collection
- **Product detail** — image gallery with per-colour filtering, variant selector, related products
- **Cart** — drawer + full page, quantity controls, shipping estimate, cross-tab sync
- **Checkout** — Stripe-hosted checkout with shipping costs, order confirmation
- **Custom pages** — CMS pages at any URL with 26 block types
- **Legal pages** — auto-generated privacy, delivery, and terms from actual shop settings
- **Search** — FTS5 full-text search with live modal, keyboard nav, ARIA
- **Contact** — contact form with order status lookup
### Theme Editor (`/admin/theme`)
Customise your shop's look without touching code:
- **8 curated presets** - Gallery, Studio, Boutique, Bold, Playful, Minimal, Night, Classic
- **Real-time preview** - See changes instantly across all page types
- **Comprehensive customisation**:
- Mood (Neutral, Warm, Cool, Dark)
- Typography (Clean, Editorial, Modern, Classic, Friendly, Minimal)
- Shape (Sharp, Soft, Round, Pill)
- Density (Compact, Balanced, Spacious)
- Accent colours with automatic contrast
- Layout options (grid columns, header style, width)
- Feature toggles (announcement bar, sticky header, etc.)
- **Logo upload** with optional SVG recolouring
- **Header image** with zoom and position controls
### Admin
- **Theme editor** — 8 presets, real-time preview, comprehensive customisation
- **Page builder** — drag-free block editor with undo/redo, live editing on shop pages
- **Analytics** — privacy-first, cookie-free, comparison mode, CSV export
- **Orders** — status tracking, fulfilment timeline, provider submission
- **Media library** — image management with alt text, usage tracking, orphan detection
- **Activity log** — global event feed, "needs attention" tab, contextual retry
- **URL redirects** — auto-redirect on slug change, 404 monitoring, dead link scanning
- **Email settings** — 10 adapter options, test email, env var precedence
- **Print providers** — Printify + Printful with sync, orders, shipping, webhooks
### Technical Highlights
- CSS custom properties for instant theme switching
- Three-layer CSS architecture (primitives → attributes → semantic)
- ETS-based CSS caching for performance
- SQLite database with BLOB storage for images
- Shared PageTemplates between preview and live shop
### Technical highlights
- Hand-written CSS with three-layer architecture (9.8 KB gzipped shop, 17.8 KB admin)
- SQLite with BLOB storage, IMMEDIATE transactions, WAL, mmap
- Image optimisation pipeline (AVIF/WebP/JPEG responsive variants via Oban)
- ETS caching for CSS, pages, redirects, favicons
- 99-100 PageSpeed mobile, no-JS support across all key flows
- 1679+ tests, CI with credo + dialyzer
## Getting Started
## Getting started
### Prerequisites
- Elixir 1.17+
- Erlang 27+
- Node.js 20+ (for assets)
- Elixir 1.19+
- Erlang/OTP 28+
- Node.js 20+ (for esbuild asset bundling)
### Setup
```bash
# Clone the repository
git clone <repo-url>
cd berrypod
# Install dependencies
mix setup
# Start the server
mix phx.server
mix setup # install deps, create DB, run migrations, build assets
mix phx.server # start dev server at localhost:4000
```
Visit:
- **Shop**: http://localhost:4000
- **Theme Editor**: http://localhost:4000/admin/theme
Visit `http://localhost:4000/setup` to create your admin account and connect a print provider.
### Running Tests
### Running tests
```bash
mix test
mix test # all tests
mix test path/to.exs # specific file
mix precommit # compile warnings + format + test (run before committing)
```
## Project Structure
## Project structure
```
lib/
├── berrypod/ # Core business logic
│ ├── settings.ex # Theme settings context
│ ├── settings/
│ │ └── theme_settings.ex # Theme settings schema
│ ├── media.ex # Image upload handling
│ └── theme/
│ ├── css_generator.ex # Generates CSS from settings
│ ├── css_cache.ex # ETS cache for generated CSS
│ ├── presets.ex # 8 theme presets
│ └── preview_data.ex # Mock data for previews
│
├── berrypod_web/ # Web layer
│ ├── components/
│ │ ├── layouts/ # App and shop layouts
│ │ ├── page_templates/ # Shared page templates (*.heex)
│ │ ├── page_templates.ex # PageTemplates module
│ │ └── shop_components.ex # Reusable shop UI components
│ ├── live/
│ │ ├── theme_live/ # Theme editor LiveView
│ │ └── shop_live/ # Public shop LiveViews
│ └── controllers/
│ └── error_html.ex # Themed error pages
lib/berrypod/ # core business logic
├── accounts.ex # user accounts + auth
├── analytics.ex # privacy-first pageview tracking
├── activity_log.ex # system event logging
├── cart.ex # session-based cart
├── media.ex # image uploads, optimisation, media library
├── newsletter.ex # email list + campaigns
├── orders.ex # order lifecycle + fulfilment
├── pages.ex # page builder (blocks, cache, defaults)
├── products.ex # products, variants, categories
├── providers.ex # POD provider abstraction (Printify, Printful)
├── redirects.ex # URL redirects + dead link monitoring
├── search.ex # FTS5 full-text search
├── settings.ex # theme + shop settings
├── shipping.ex # shipping rates + country detection
├── theme/ # CSS generation, presets, ETS cache
└── workers/ # Oban background jobs
lib/berrypod_web/ # web layer
├── components/
│ ├── layouts/ # app, admin, and shop layouts
│ ├── shop_components/ # shop UI (product cards, cart, gallery, etc.)
│ └── block_editor_components.ex
├── live/
│ ├── admin/ # admin LiveViews (orders, pages, media, etc.)
│ ├── shop/ # shop LiveViews (home, collection, product, etc.)
│ └── auth/ # authentication
├── page_renderer.ex # generic block-to-component dispatch
└── controllers/ # Stripe webhooks, favicons, images, cart API
assets/css/
├── app.css # Main stylesheet
├── theme-layer1-primitives.css # Design tokens
├── theme-layer2-attributes.css # Theme-specific values
└── theme-layer3-semantic.css # Component styles
├── shop/ # shop component styles
├── admin/ # admin component styles
├── theme-layer1-primitives.css # design tokens
├── theme-layer2-attributes.css # theme-specific values
└── theme-layer3-semantic.css # component styles
```
## Routes
| Path | Description |
|------|-------------|
| `/` | Shop home page |
| `/collections/all` | All products |
| `/collections/:slug` | Category collection (filterable) |
| `/products/:id` | Product detail page |
| `/cart` | Shopping cart |
| `/checkout` | Create Stripe session (POST) |
| `/checkout/success` | Order confirmation |
| `/webhooks/stripe` | Stripe webhook endpoint |
| `/about` | About page |
| `/contact` | Contact page |
| `/admin/theme` | Theme editor (requires auth) |
| `/dev/errors/404` | Preview 404 page (dev only) |
| `/dev/errors/500` | Preview 500 page (dev only) |
## Stripe Checkout
Berrypod uses [Stripe Checkout](https://stripe.com/docs/payments/checkout) (hosted payment page) for secure payment processing.
### Setup
## Stripe setup
1. Create a [Stripe account](https://dashboard.stripe.com/register)
2. Get your API keys from the [Stripe Dashboard](https://dashboard.stripe.com/test/apikeys)
3. Set environment variables:
```bash
export STRIPE_SECRET_KEY="sk_test_..."
export STRIPE_WEBHOOK_SECRET="whsec_..."
```
### Local webhook testing
Use the [Stripe CLI](https://stripe.com/docs/stripe-cli) to forward webhooks to your local server:
2. Navigate to Admin > Settings in your shop
3. Paste your secret key and click "Connect Stripe"
For local webhook testing:
```bash
stripe listen --forward-to localhost:4000/webhooks/stripe
```
The CLI will print a webhook signing secret — use that as `STRIPE_WEBHOOK_SECRET`.
### Test cards
| Number | Result |
|--------|--------|
| `4242 4242 4242 4242` | Successful payment |
| `4000 0000 0000 0002` | Declined |
| `4000 0025 0000 3155` | Requires 3D Secure |
Use any future expiry date and any 3-digit CVC.
## Generating Mockups
The project includes a Printify integration for generating product mockups. This is useful for creating sample product images from Unsplash artwork.
### Prerequisites
1. A Printify account with API access
2. Set the `PRINTIFY_API_TOKEN` environment variable
### Usage
```bash
# Generate all mockups (saves to priv/static/mockups/)
export PRINTIFY_API_TOKEN="your-token"
mix generate_mockups
# Generate mockups and delete products from Printify afterwards
mix generate_mockups --cleanup
# Search for available blueprints
mix generate_mockups --search "poster"
# List all blueprints
mix generate_mockups --list-blueprints
```
Product definitions are in `lib/berrypod/printify/mockup_generator.ex`.
Test cards: `4242 4242 4242 4242` (success), `4000 0000 0000 0002` (declined).
## Documentation
- [ROADMAP.md](ROADMAP.md) - Future features and improvements
- [docs/plans/](docs/plans/) - Feature plans
- [docs/research/](docs/research/) - Design research and guidelines
## Design Philosophy
1. **"One theme, infinite variations"** - Rather than multiple themes, 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
- [PROGRESS.md](PROGRESS.md) — current status and next tasks
- [ROADMAP.md](ROADMAP.md) — future vision and planned features
- [CLAUDE.md](CLAUDE.md) — coding guidelines and conventions
- [docs/plans/](docs/plans/) — feature implementation plans
## License