# frappe/webshop architecture

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

- Interactive diagram: https://gitdiagram.com/frappe/webshop
- Repository: https://github.com/frappe/webshop

## Overview

##### Project Type and Purpose
- Type: Frappe Webshop is a full-stack, open-source eCommerce application built on the Frappe framework (Python back end + Jinja/JavaScript front end).
- Purpose: To enable small and medium businesses to spin up customizable online stores; integrates with ERPNext for inventory, billing, and order management.

##### File Structure
- Top-level:
– `.github`, CI/CD pipelines
– `pyproject.toml`, packaging and dependencies
– `webshop/`: main Python package
- `webshop/hooks.py`: Frappe hooks into events
- `webshop/patches/`: data-migration and patch scripts applied at install/upgrade
- `webshop/setup/`: installer entry point
- `webshop/public/`: static assets (JS, SCSS, images) served to clients
- `webshop/templates/`: Jinja templates for website pages, includes, and generators
- `webshop/webshop/`: core Python modules
– `api.py`: REST or RPC endpoints
– `crud_events/`: doctype event handlers (e.g., revalidate cart when price_list changes)
– `doctype/`: DocType definitions (schemas, JS clients, Python controllers, tests)
– `product_data_engine/`: search & filtering logic
– `shopping_cart/`, `variant_selector/`: business logic modules
– `utils/`, `redisearch_utils.py`: helpers and cache/search integrations
– `web_template/`: configurable website components (hero slider, product cards)
- `webshop/www/`: “website application” pages (each folder is a URL route).

##### README
- Confirms full-stack eCommerce app on Frappe
- Key technologies: Python, JavaScript, SCSS, Redis, MariaDB (via Frappe)
- Integrates with ERPNext and external payment gateways (Stripe, PayPal)
- Deployment via Bench (Docker or VMs), uses Redis for caching & job queuing.

##### Main Components & Their Interactions
a. Client Layer
– Web Browser / Mobile Browser
– Static Assets: HTML (from Jinja templates), JS modules (`webshop/public/js/...`), SCSS bundles
– Pages: `webshop/www/<route>`, dynamic JS behavior (cart, wishlist, search)
b. Application Layer (Frappe Server)
– HTTP Server (Nginx → Gunicorn / bench served)
– Frappe Framework
- Hooks & Patches: `hooks.py` and `patches/` on install/upgrade
- DocTypes: data models and form controllers
- CRUD Event Handlers: business rules triggered on document changes
- API Endpoints (`api.py`) for AJAX/REST calls
- Product Engine & Cart Logic: search, filtering, cart operations
– Bench Workers & Scheduler (background jobs, patch runner)
c. Data Layer
– MariaDB (primary DocType storage)
– Redis (cache, full-text search via redisearch_utils, job queue)
d. External Integrations
– ERPNext (via Frappe’s internal RPC)
– Payment Gateways (Stripe, PayPal)
– Optional Email/SMS providers for order notifications

##### Architectural Patterns & Design Principles
- MVC-style:
– Model = DocTypes
– View = Jinja templates + website pages + front-end JS
– Controller = server-side Python in pages, `api.py`, and event handlers
- Modular & Pluggable: Patches, Hooks, and Web Templates allow customization without core changes
- Separation of Concerns:
– Static asset pipeline in `public/`
– Template generators in `templates/generators/`
– Pure business logic in `webshop/webshop/…`

##### Essential Elements
– Clear, self-explanatory labels on each component
– Annotations for critical customizations (Hooks, Patches)
– Versioning/deployment context (e.g., Bench → Docker containers)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["Web/Mobile Browser"]:::frontEnd
        StaticAssets["Static Assets (HTML, CSS, JS)"]:::frontEnd
        JSModules["JavaScript Modules"]:::frontEnd
        Stylesheets["Stylesheets (SCSS)"]:::frontEnd
        WebsiteRoutes["Website Routes (URL handlers)"]:::frontEnd
        Templates["Jinja Templates (Views)"]:::frontEnd
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        NginxGunicorn["Nginx → Gunicorn (HTTP Server)"]:::infra
        Hooks["Frappe Hooks"]:::backEnd
        Patches["Data-Migration & Upgrade Patches"]:::backEnd
        Installer["Installer Entry Point"]:::backEnd
        APIEndpoints["REST/RPC API Endpoints"]:::backEnd
        DocTypes["DocType Definitions (Models & Controllers)"]:::backEnd
        CRUDEvents["DocType Event Handlers (CRUD Events)"]:::backEnd
        ProductEngine["Product Search & Filtering Engine"]:::backEnd
        ShoppingCart["Shopping Cart Business Logic"]:::backEnd
        VariantSelector["Variant Selector Logic"]:::backEnd
        RedisUtils["Redis & Full-Text Search Utilities"]:::backEnd
        Utils["Helper Utilities"]:::backEnd
        WebTemplates["Web Template Components"]:::backEnd
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        MariaDB["MariaDB (DocType Storage)"]:::infra
        Redis["Redis (Cache, Queue, Search)"]:::infra
    end

    %% External Services
    subgraph "External Services"
        direction TB
        ERPNext["ERPNext (RPC Integration)"]:::external
        PaymentGateways["Payment Gateways (Stripe, PayPal)"]:::external
    end

    %% Connections
    Browser -->|HTTP Request| NginxGunicorn
    NginxGunicorn -->|Serves Static| StaticAssets
    NginxGunicorn -->|Serves Templates| Templates
    NginxGunicorn -->|Routes to| WebsiteRoutes
    StaticAssets --> Browser
    Templates --> Browser
    WebsiteRoutes --> Browser
    Browser -->|Loads Modules| JSModules
    Browser -->|Loads Styles| Stylesheets

    NginxGunicorn -->|Forwards API Calls| APIEndpoints
    APIEndpoints -->|Read/Write| DocTypes
    APIEndpoints -->|Trigger| CRUDEvents
    CRUDEvents -->|SQL Queries| MariaDB
    DocTypes -->|SQL Queries| MariaDB
    ProductEngine -->|Redisearch Commands| Redis
    ShoppingCart -->|Cache Operations| Redis
    VariantSelector -->|Data Access| RedisUtils
    APIEndpoints -->|Use| ProductEngine
    APIEndpoints -->|Use| ShoppingCart
    APIEndpoints -->|Use| VariantSelector
    APIEndpoints -->|Use| Utils
    APIEndpoints -->|Render| WebTemplates

    Hooks -->|On Install/Upgrade| Patches
    Installer -->|Runs| Hooks
    Patches -->|Alter Data| MariaDB

    APIEndpoints -->|RPC Calls| ERPNext
    APIEndpoints -->|Payment Requests| PaymentGateways

    %% Click Events
    click StaticAssets "https://github.com/frappe/webshop/tree/develop/webshop/public"
    click JSModules "https://github.com/frappe/webshop/tree/develop/webshop/public/js"
    click Stylesheets "https://github.com/frappe/webshop/tree/develop/webshop/public/scss"
    click WebsiteRoutes "https://github.com/frappe/webshop/tree/develop/webshop/www"
    click Templates "https://github.com/frappe/webshop/tree/develop/webshop/templates"
    click Hooks "https://github.com/frappe/webshop/blob/develop/webshop/hooks.py"
    click Patches "https://github.com/frappe/webshop/tree/develop/webshop/patches/"
    click Installer "https://github.com/frappe/webshop/blob/develop/webshop/setup/install.py"
    click APIEndpoints "https://github.com/frappe/webshop/blob/develop/webshop/webshop/api.py"
    click DocTypes "https://github.com/frappe/webshop/tree/develop/webshop/webshop/doctype/"
    click CRUDEvents "https://github.com/frappe/webshop/tree/develop/webshop/webshop/crud_events/"
    click ProductEngine "https://github.com/frappe/webshop/tree/develop/webshop/webshop/product_data_engine/"
    click ShoppingCart "https://github.com/frappe/webshop/tree/develop/webshop/webshop/shopping_cart/"
    click VariantSelector "https://github.com/frappe/webshop/tree/develop/webshop/webshop/variant_selector/"
    click RedisUtils "https://github.com/frappe/webshop/blob/develop/webshop/webshop/redisearch_utils.py"
    click Utils "https://github.com/frappe/webshop/tree/develop/webshop/webshop/utils/"
    click WebTemplates "https://github.com/frappe/webshop/tree/develop/webshop/webshop/web_template/"

    %% Styles
    classDef frontEnd fill:#D6EFFF,stroke:#0366d6
    classDef backEnd fill:#D6FFD6,stroke:#28a745
    classDef infra fill:#FFE7C1,stroke:#d58512
    classDef external fill:#E8DAFF,stroke:#6f42c1
```
