# awesto/django-shop architecture

> Architecture diagram of the GitHub repository awesto/django-shop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/awesto/django-shop
- Repository: https://github.com/awesto/django-shop

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Presentation Layer"
        WebClient["Web Client (Browser/SPA/Mobile)"]:::presentation
        Templates["Templates"]:::presentation
        StaticAssets["Static Assets (CSS/JS/Images)"]:::presentation
        cmsComposer["CMS Page Composer"]:::presentation
    end

    subgraph "Application Layer"
        Router["URL Dispatcher / Router"]:::application
        HTMLViews["HTML Views"]:::application
        RESTAPI["REST Endpoints"]:::application
        Cascade["Cascade/Plugin Engine"]:::application
        CartModifiers["Cart Modifiers"]:::application
        PaymentModules["Payment Modifiers & Workflows"]:::application
        ShippingModules["Shipping Modifiers & Workflows"]:::application
        OrderFSM["Order State Machine (FSM)"]:::application
        AdminUI["Administrative Interface"]:::application
    end

    subgraph "Data Layer"
        ORM["Django ORM Models"]:::data
        Migrations["Migrations"]:::data
        DB["Relational Database"]:::data
        SearchIndex["Search Index Store"]:::data
    end

    subgraph "External Services"
        PaymentProv["Payment Providers"]:::external
        ShippingProv["Shipping Providers"]:::external
        EmailService["Email Service"]:::external
        CMSHost["django-CMS Host"]:::external
        WorkerQueue["Background Worker/Queue"]:::external
    end

    WebClient -->|"HTTP(S) Request"| Router
    Router -->|"routes to"| HTMLViews
    Router -->|"routes to"| RESTAPI
    Router -->|"routes to"| AdminUI

    HTMLViews -->|"renders"| Templates
    HTMLViews -->|"serves"| StaticAssets
    HTMLViews -->|"invokes"| Cascade

    RESTAPI -->|"uses"| Cascade
    RESTAPI -->|"queries"| SearchIndex

    cmsComposer -->|"composes pages via"| Cascade
    cmsComposer -->|"search plugin queries"| SearchIndex
    CMSHost -->|"hosts composer"| cmsComposer

    Cascade -->|"applies modifiers"| CartModifiers
    Cascade -->|"applies modifiers"| PaymentModules
    Cascade -->|"applies modifiers"| ShippingModules
    Cascade -->|"triggers workflow"| OrderFSM

    CartModifiers -->|"reads/writes"| ORM
    PaymentModules -->|"reads/writes"| ORM
    ShippingModules -->|"reads/writes"| ORM
    OrderFSM -->|"transitions on models"| ORM

    ORM -->|"persists to"| DB
    OrderFSM -->|"dispatches tasks to"| WorkerQueue

    WorkerQueue -->|"calls"| PaymentProv
    WorkerQueue -->|"calls"| ShippingProv
    WorkerQueue -->|"sends via"| EmailService

    classDef presentation fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef application fill:#90EE90,stroke:#000,stroke-width:1px
    classDef data fill:#FFA500,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px

    click Core "https://github.com/awesto/django-shop/tree/master/shop/"
    click EmailAuth "https://github.com/awesto/django-shop/tree/master/email_auth/"
    click Templates "https://github.com/awesto/django-shop/tree/master/shop/templates/shop/"
    click StaticAssets "https://github.com/awesto/django-shop/tree/master/shop/static/shop/"
    click cmsComposer "https://github.com/awesto/django-shop/blob/master/shop/cascade/plugin_base.py"
    click CMSHost "https://github.com/awesto/django-shop/blob/master/shop/cms_apphooks.py"
    click Router "https://github.com/awesto/django-shop/tree/master/shop/urls/"
    click HTMLViews "https://github.com/awesto/django-shop/tree/master/shop/views/"
    click RESTAPI "https://github.com/awesto/django-shop/tree/master/shop/rest/"
    click CartModifiers "https://github.com/awesto/django-shop/tree/master/shop/modifiers/"
    click PaymentModules "https://github.com/awesto/django-shop/blob/master/shop/payment/modifiers.py"
    click ShippingModules "https://github.com/awesto/django-shop/blob/master/shop/shipping/modifiers.py"
    click OrderFSM "https://github.com/awesto/django-shop/blob/master/shop/transition.py"
    click AdminUI "https://github.com/awesto/django-shop/tree/master/shop/admin/"
    click ORM "https://github.com/awesto/django-shop/tree/master/shop/models/"
    click Migrations "https://github.com/awesto/django-shop/tree/master/shop/migrations/"
    click SearchIndex "https://github.com/awesto/django-shop/tree/master/shop/search/"
    click WorkerQueue "https://github.com/awesto/django-shop/blob/master/docs/reference/worker.rst"
```
