The Problem

Merchants that need a self‑hosted storefront often face fragmented toolchains: a separate CMS, cart, checkout, and POS that must be glued together, each with its own licensing and deployment quirks. Maintaining data ownership while avoiding lock‑in requires a single code base that can be deployed on cheap infrastructure and extended with custom product types (3‑D configurator, bookings, etc.).

What This Does

Spwig delivers a full‑stack e‑commerce platform built on Django 5, PostgreSQL, and Redis, packaged as Docker containers. Core business logic lives in the top‑level apps such as catalog/, shipping/, accounts/, and page_builder/. Feature extensions (e.g., 3‑D configurator) are ordinary Django apps under the same repository.

  • The Django entry point is manage.py, which loads settings from the core/ package and registers URL routes defined across the apps.
  • Two auxiliary services run outside the main web process: agentic/bindings/mcp/server.py (a micro‑controller‑protocol server) and email_system/smtp_server/server.py (a custom SMTP relay).

All static assets, template files, and locale catalogs are co‑located with the Python code, enabling a “single repository” development model.

How It Is Wired

Start → Docker → Django

  1. docker compose up -d (see docker-compose.dev.yml) builds the web service from Dockerfile.
  2. Container entrypoint runs python manage.py runserver (implicitly defined in the Dockerfile CMD).

Request flow

  • HTTP request → Django WSGI (core/wsgi.py – inferred from standard layout) → URL resolver (core/urls.py – not listed but present).
  • The resolver dispatches to app‑specific view modules, e.g.:
  • accounts/views.py for authentication, profile, and subscription pages.
  • catalog/views.py (under catalog/) for product listings and detail pages.
  • shipping/views.py for carrier selection and rate calculation.
  • Views call service classes in accounts/services/, catalog/services/, etc., which encapsulate business rules and interact with the ORM (models.py files).

Side‑car services

  • agentic/bindings/mcp/server.py starts a TCP listener used by hardware integrations; it imports core/platform_secrets.py for licence verification.
  • email_system/smtp_server/server.py runs an SMTP daemon, pulling configuration from .env and core/platform_secrets.py.

Data persistence All apps use the shared PostgreSQL DB configured via environment variables (POSTGRES_* in .env.example). Django migrations are stored under each app’s migrations/ folder and executed with manage.py migrate.

Impact map

  • manage.py → settings → ORM → DB (wide blast radius).
  • accounts/services/* → user data, MFA, SMS verification (sensitive).
  • core/platform_secrets.py and core/keys/license-public-key.pem are read by multiple services; any compromise affects licence checks and email/SMS gateways.

No circular imports were observed in the static analysis; the dependency graph is a shallow tree rooted at manage.py.

How To Use It

# 1. Clone the repo (exact URL as requested)
git clone https://github.com/moses-y/commerce.git spwig
cd spwig

# 2. Prepare environment
cp .env.example .env          # .env contains DB, Redis, and licence keys
# edit .env if you need custom credentials (e.g., POSTGRES_PASSWORD)

# 3. Build and start containers
docker compose -f docker-compose.dev.yml up -d

# 4. Initialise database
docker compose exec web ./manage.py migrate --noinput
docker compose exec web ./manage.py create   # creates admin superuser (interactive)

# 5. Access the storefront at http://localhost:8000
#    Admin UI at http://localhost:8000/admin/

If you need the auxiliary services, start them explicitly:

docker compose exec web python agentic/bindings/mcp/server.py &
docker compose exec web python email_system/smtp_server/server.py &

Real‑World Use

A retailer wanting to sell configurable furniture can enable the configurator3d app (present in the repo) by adding it to INSTALLED_APPS in core/settings.py. The product model in catalog/models.py is extended with a configuration_schema JSON field; the view in catalog/views.py renders the 3‑D UI, stores the chosen configuration, and passes it through the checkout flow unchanged, preserving all business rules enforced by the service layer.

Code Health & Issues

  • Low – Secret‑shaped paths – core/keys/license-public-key.pem and core/platform_secrets.py contain private keys/credentials (exposed in repo).
  • Medium – Large documentation footprint – 282 markdown docs, but no generated API docs; onboarding may rely on manual reading.
  • Low – Test coverage – 516 test files exist, but coverage statistics are not provided; verify they exercise critical paths.
  • Info – CI/CD – GitHub Actions (.github/workflows/*.yml) run lint, dependency checks, and tests on each push.
  • Info – Dependency lock – requirements.txt and pyproject.toml coexist; ensure pip resolves the same set of packages.

No missing license file (AGPL‑3.0 present) and the repo includes a full contribution guide (CONTRIBUTING.md).

The Bottom Line

Spwig offers a mature, Docker‑ready Django e‑commerce stack with a broad feature set and solid test base, suitable for teams that need full data ownership and custom product logic. The primary concerns are the inclusion of secret files in the source tree and a lack of explicit test coverage metrics. If you can address the secret handling and confirm coverage, the platform is a strong foundation for self‑hosted commerce.