pypiggyback 0.1.0

Design, save, and send beautiful occasion cards — a Moonpig-style Django plugin

Piggyback 🐷

Design, save, and send beautiful occasion cards in Django.

Piggyback is a Moonpig-style Django plugin that lets your users design personalised greeting cards, save them to a library, and send by email or post — with a full REST API, card editor, address book, reminders, gift add-ons, and checkout flow.

Landing Page · Documentation · API Reference

---

Features

Feature	Description
Card Designer	Fabric.js editor with Alpine.js UI + HTMX send flow
Card Shop	Browse templates by occasion (birthday, wedding, sympathy…) and style
Card Library	Auto-synced drafts, saved designs, sent cards, favourites
E-Cards	Instant email delivery with branded view page
Posted Cards	Pluggable postal fulfilment backend
Address Book	Recipients with email, postal address, birthdays
Reminders	Cron-ready birthday/anniversary email reminders
Gift Add-ons	Chocolates, candles, prosecco, gift wrap
Checkout	Cart, promo codes, payment hooks (Stripe-ready)
REST API	Full DRF API for headless/mobile integrations
Admin	Django admin for all models

Docker

docker compose up --build

Open http://localhost:8000 — demo login demo / demo12345. See Docker docs.

Quick install

pip install pypiggyback

# settings.py
INSTALLED_APPS = [
    # ...
    "rest_framework",
    "django_filters",
    "piggyback",
]

# urls.py
urlpatterns = [
    path("", include("piggyback.urls")),
]

python manage.py migrate
python manage.py load_sample_data
python manage.py runserver

Visit http://localhost:8000 — browse cards, open the editor, sign in via /admin/login/ to save and send.

Run the Example Project

git clone https://github.com/kurtisrogers/piggyback.git
cd piggyback
pip install -e ".[dev]"
cd example
python manage.py migrate
python manage.py load_sample_data
python manage.py createsuperuser
python manage.py runserver

API Example

# Browse templates (no auth)
curl http://localhost:8000/api/templates/

# Personalise a template (authenticated)
curl -X POST http://localhost:8000/api/templates/birthday-general-classic/personalize/ \
  -b "sessionid=YOUR_SESSION"

# Add to cart and checkout
curl -X POST http://localhost:8000/api/orders/add_to_cart/ \
  -H "Content-Type: application/json" \
  -d '{"card_id": 1, "recipient_id": 1, "delivery_method": "ecard"}'

Configuration

PIGGYBACK_PUBLIC_URL = "https://cards.yoursite.com"
PIGGYBACK_ECARD_PRICE = 299          # pence (£2.99)
PIGGYBACK_POSTED_CARD_PRICE = 399
PIGGYBACK_REMINDER_DAYS_BEFORE = [7, 3, 1]

# Reuse existing User/profile details (no duplicate data entry)
PIGGYBACK_USER_PROFILE_RELATION = "profile"
PIGGYBACK_PROFILE_FIELD_MAP = {"phone": "phone_number", "address_line_1": "line1", ...}

See the configuration docs and system user details guide.

Project Structure

src/piggyback/          # Django app
├── models/             # Catalog, cards, orders, recipients, reminders
├── api/                # DRF viewsets and serializers
├── views/              # Web UI views
├── services/           # Delivery, checkout, rendering, reminders
├── templates/          # HTML templates + email templates
├── static/             # CSS + Fabric.js editor
└── management/         # load_sample_data, send_reminders

example/                # Demo Django project
docs/                   # MkDocs documentation
landing/                # GitHub Pages landing page
tests/                  # pytest suite

Development

pip install -e ".[dev]"
pre-commit install
playwright install chromium
pytest                              # unit + BDD (22 tests)
pre-commit run --all-files
mkdocs serve -f docs/mkdocs.yml

• Fixtures: python manage.py load_sample_data --fixture
• Unit tests: pytest tests/ --ignore=tests/bdd
• BDD E2E: pytest tests/bdd (Playwright + Gherkin)
• Branch protection: see docs/development/branch-protection.md (requires repo admin)

License

MIT — see LICENSE.