Skip to content

arvel-ecommerce-kit

Introduction

arvel-ecommerce-kit is a full-stack e-commerce reference application. Read it to see how Arvel's features fit together in a real app, or scaffold a new project from it.

This is an example, not a library you depend on. Use it as a worked example.

What It Includes

  • Backend — an Arvel API: storefront, cart, checkout, account, admin CRUD, RBAC, i18n, and media.
  • Frontend — a Vue 3 SPA (storefront + admin) with an Orval-generated API client.
  • Infra — Docker Compose with Postgres, Redis, the backend, the frontend dev server, and a scheduler worker.

Scaffolding From the Kit

The kit doubles as a scaffolding source. It's not on PyPI and isn't bundled in the arvel wheel — instead it ships as a tarball attached to its own GitHub Release (arvel-ecommerce-kit-v*). Just run:

arvel new my-shop --kit ecommerce

The CLI resolves the newest arvel-ecommerce-kit-v* release, downloads the tarball (with a progress bar), verifies it against the release's .sha256 sidecar, caches it under ~/.cache/arvel/kits/, renames the project to my-shop, and runs uv sync --all-extras --dev. Inside an Arvel checkout the local workspace copy is used instead, so contributors never hit the network.

Pin a specific version (and skip the release lookup) with ARVEL_ECOMMERCE_KIT_VERSION:

ARVEL_ECOMMERCE_KIT_VERSION=1.0.0 arvel new my-shop --kit ecommerce

If the download can't be reached, the command fails with a KitDownloadError that points you back at the repo.

Running the Bundled App

Prerequisites

Everything runs in containers, so the host only needs:

  • Docker Engine with the Compose plugin (docker compose).
  • GNU Make.
  • uv — to install and run the Arvel CLI (uv tool install arvel) for scaffolding and host-side arvel commands.
  • Free local ports: 8001 (backend), 8000 (frontend), 5432 (Postgres), 6379 (Redis). Override them in .env if they clash.

Commands

make env       # copy .env.example to .env
make up        # start db, redis, backend, frontend, then wait until all are healthy
make healthcheck    # wait until every service reports healthy
make migrate   # arvel migrate (inside the backend container)
make seed      # arvel db:seed

Default URLs (from .env.example):

  • Backend: http://localhost:8001 — health at GET /healthz
  • Frontend: http://localhost:8000

Run the tests with make test-backend and make test-frontend.

Note

make up starts Postgres, Redis, the backend, and the frontend. The scheduler service is defined in docker-compose.yml but is brought up by make seed, not make up. Queue (RabbitMQ), mail, and S3 are configured and exercised in the backend tests via testcontainers, but aren't started by the default Compose file.

Where to Look for Each Feature

Use these files as worked examples while reading the rest of the docs:

Topic Start here
App bootstrap & middleware stack backend/bootstrap/app.py
Full route map backend/routes/api.py
Provider wiring backend/bootstrap/providers.py, backend/app/providers/app_service_provider.py
Auth (JWT + refresh cookies + CSRF) backend/config/auth.py, backend/app/http/controllers/ (auth controller)
Roles & permissions backend/app/models/user.py, backend/config/permission.py, backend/app/http/controllers/admin/users.py
Catalog domain & media backend/app/models/product.py, product_base.py, backend/app/services/media_service.py
Cart / checkout backend/app/services/cart_service.py, order_service.py, tests/feature/test_cart_and_checkout.py
Materialized view + refresh backend/app/support/products_catalog.py, backend/app/console/kernel.py
Observers backend/app/observers/
Resources (serialization) backend/app/http/resources/
OpenAPI export Makefile (api-generate target)

It pulls in several companion packages — arvel[permission] for RBAC and arvel[image] for product media — alongside Postgres, Redis, queues, mail, and S3 extras.