How awesto/django-shop works
Project type and purpose
• This is a reusable, full-stack Django e-commerce framework (“django-SHOP”) designed to plug into Django and django-CMS.
• It exposes both template-rendered HTML views and RESTful endpoints, supports pluggable cart modifiers, state-machine-driven order workflows, payment/shipping provider integrations, search indexing, and a modular CMS plugin architecture.
File structure
• Top level:
• shop/ – the core Django app (models, views, admin, templates, static assets, cascade/plugins, payment, shipping, REST, search, serializers, workflows)
• email_auth/ – extension providing email-based authentication
• docs/, README.md, setup.py, tox.ini, CI configuration
• tests/ – test suite covering auth, cart, catalog, checkout, orders, money, inventory, etc.
• Key architectural patterns:
• MVC (Django models, views, templates)
• Component/plugin-based page composition (shop/cascade, cms_apphooks)
• Pluggable cart modifiers and workflows (shop/modifiers, shop/payment, shop/shipping, shop/transition)
• REST API layer (shop/rest, shop/serializers)
• Internationalization (shop/locale)
• Administrative interface (shop/admin)
• Search integration (shop/search)
• Background worker tasks (docs/reference/worker.rst)
README for additional insights
• Emphasizes “compose pages using plugins,” dual delivery of HTML and REST, pluggable modifiers and workflows, modular design and third-party extension points for payment/shipping/search.
Main components
a. Presentation Layer
• Web client / Single Page App (browser or mobile)
• Static assets (CSS/JS/images served via Django staticfiles or CDN)
• django-CMS page composer integrating shop plugins
b. Application Layer
• URL Dispatcher / Router (shop/urls/*.py)
• Views
– HTML Views (shop/views/*.py)
– REST Endpoints (shop/rest/, Django REST Framework)
• Cascade/plugin engine (shop/cascade) responsible for constructing page fragments (catalog, cart, checkout, order)
• Business logic
– Cart modifiers (shop/modifiers, shop/payment/modifiers, shop/shipping/modifiers)
– Order workflow (finite-state machine in shop/transition)
• Administrative UI (Django admin extensions under shop/admin)
c. Data Layer
• Django ORM models (shop/models and shop/models/defaults)
• Migrations (shop/migrations, email_auth/migrations)
• Database (PostgreSQL, MySQL, etc.)
• Search index store (Elasticsearch or similar via shop/search)
d. Integration & External Services
• Payment providers (PayPal, Stripe, custom; via shop/payment/providers)
• Shipping providers (SendCloud, custom; via shop/shipping/providers)
• Email service for notifications (SMTP or transactional email service)
• django-CMS (page composition host)
• Optional background worker/queue (Celery/RQ; referenced in docs/reference/worker.rst)
Relationships and interactions
• Client → HTTP(S) → Router → View
• If HTML: View → Template renderer → Response + static asset calls
• If REST: View → Serializer → JSON → Response
• Views invoke cascade/plugin engine to assemble components
• Components call cart modifiers to compute pricing/taxes/shipping, and order workflow to enforce state transitions
• Business logic reads/writes Django models → relational DB
• On certain events (order placed, status change) tasks are dispatched to background worker and external services (payment capture, shipping label generation, email notifications)
• Data is indexed via shop/search into external search backend; client or CMS search plugin queries the index
Architectural patterns & design principles
• Modular plugin architecture (shop/cascade/plugin_base.py) for page composition
• Pluggable interfaces for cart modifiers and workflows (strategy and state-machine patterns)
• Clear separation of concerns: presentation, application logic, data, integrations
• Use of Django’s admin, ORM, signals, and internationalization framework
• Dual interface: monolithic HTML and headless REST API
• Clear, self-explanatory labels on all components and boundaries
• Annotations to call out pluggable interfaces and key extension hooks