Skip to content

Architecture Diagrams

Visual documentation of the Freeze Design webshop architecture, data and workflows. Every diagram is generated from Mermaid source in this page and reflects the code on staging as of 2026-11-02 (v1.58).

Color Legend

Color Meaning
๐ŸŸฆ Blue Frontend (Next.js/React)
๐ŸŸฉ Green Backend (Django/DRF/Celery)
๐ŸŸง Orange External services
๐ŸŸช Purple Database/storage
โฌœ Gray Users/actors

1. System Context

The system, its users and the external services it talks to.

flowchart TB
    subgraph users[" ๐Ÿ‘ฅ Users "]
        customer["๐Ÿ›’ Customer<br/><small>browse, design, order</small>"]
        staff["โš™๏ธ Staff (Eefje)<br/><small>Next.js admin</small>"]
    end

    subgraph system["๐Ÿช Freeze Design Webshop"]
        frontend["๐Ÿ–ฅ๏ธ Next.js 16"]
        backend["โšก Django 6 + DRF<br/><small>+ Celery</small>"]
        postgres[("๐Ÿ˜ PostgreSQL 15")]
        redis[("โšก Redis 7")]
    end

    subgraph external[" โ˜๏ธ External Services "]
        mollie["๐Ÿ’ณ Mollie<br/><small>payments, refunds</small>"]
        resend["๐Ÿ“ง Resend<br/><small>email + newsletter contacts</small>"]
        spaces["๐Ÿ“ฆ DO Spaces<br/><small>media + DB backups</small>"]
        informer["๐Ÿ“’ Informer<br/><small>bookkeeping, off by default</small>"]
        google["โญ Google Places<br/><small>reviews block</small>"]
        sentry["๐Ÿ› Sentry"]
        posthog["๐Ÿ“Š PostHog (EU)"]
        discord["๐Ÿ’ฌ Discord webhooks"]
    end

    customer --> frontend
    staff --> frontend
    frontend <--> backend
    backend <--> postgres
    backend <--> redis
    backend --> mollie
    mollie -->|"webhook"| backend
    backend --> resend
    backend --> spaces
    backend -->|"sales invoice per paid order"| informer
    backend -->|"rating + reviews"| google
    backend --> sentry
    frontend --> sentry
    frontend -->|"/ingest/ proxy"| posthog
    backend -->|"read-only API"| posthog
    backend --> discord

    style frontend fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style backend fill:#10b981,stroke:#059669,color:#fff
    style postgres fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style redis fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style mollie fill:#f97316,stroke:#ea580c,color:#fff
    style resend fill:#f97316,stroke:#ea580c,color:#fff
    style spaces fill:#f97316,stroke:#ea580c,color:#fff
    style informer fill:#f97316,stroke:#ea580c,color:#fff
    style google fill:#f97316,stroke:#ea580c,color:#fff
    style sentry fill:#f97316,stroke:#ea580c,color:#fff
    style posthog fill:#f97316,stroke:#ea580c,color:#fff
    style discord fill:#5865f2,stroke:#4752c4,color:#fff
    style customer fill:#6b7280,stroke:#4b5563,color:#fff
    style staff fill:#6b7280,stroke:#4b5563,color:#fff

PostHog is instrumented in the frontend only on shop routes (instrumentation-client.ts init, PostHogProvider $pageview, lib/posthog.ts typed events; requests go through the /ingest/ rewrite in next.config.ts). The backend reads PostHog and Sentry with read-only keys for the admin "Website" tiles (apps/analytics/website.py). Google Merchant Center, Meta and Pinterest are not drawn: they pull GET /api/feeds/google-shopping.xml themselves. WhatsApp is only a wa.me link in the footer and on the product page / designer.


2. Request Path and Containers

How a request travels from the browser through nginx to the two runtimes, and which container owns which data store.

flowchart TB
    browser["๐ŸŒ Browser"]
    dns["DNS<br/><small>Openprovider, A records straight to the VPS</small>"]

    subgraph vps["๐Ÿ–ฅ๏ธ VPS โ€” Docker Compose"]
        nginx["๐Ÿ”€ nginx :80/:443<br/><small>TLS, HSTS, static/media, basic auth on staging</small>"]
        nextjs["โš›๏ธ frontend :3000<br/><small>Next.js SSR + client</small>"]
        django["๐Ÿ backend :8000<br/><small>Gunicorn + Django</small>"]
        worker["โฐ celery<br/><small>worker</small>"]
        beat["๐Ÿ“… celery-beat<br/><small>schedule</small>"]
        pg[("๐Ÿ˜ postgres")]
        rd[("โšก redis")]
    end

    spaces["๐Ÿ“ฆ DO Spaces<br/><small>/media/ in deployed envs</small>"]

    browser --> dns --> nginx
    nginx -->|"/ ยท /_next/static/"| nextjs
    nginx -->|"/api/ ยท /_allauth/ ยท /django-admin/"| django
    nextjs -->|"server-side fetch"| django
    django --> pg
    django --> rd
    django -.->|"tasks"| rd
    rd -.-> worker
    beat --> rd
    worker --> pg
    django --> spaces
    worker --> spaces

    style browser fill:#6b7280,stroke:#4b5563,color:#fff
    style nginx fill:#009639,stroke:#007a2f,color:#fff
    style nextjs fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style django fill:#10b981,stroke:#059669,color:#fff
    style worker fill:#10b981,stroke:#059669,color:#fff
    style beat fill:#10b981,stroke:#059669,color:#fff
    style pg fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style rd fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style spaces fill:#f97316,stroke:#ea580c,color:#fff

3. Frontend Architecture

Provider stack per route group and the layers a page goes through to reach the API.

flowchart TB
    subgraph root["app/layout.tsx"]
        sentry_p["SentryProvider + StagingBanner"]
    end

    subgraph shop["app/(shop)/layout.tsx"]
        shop_stack["QueryProvider โ†’ ThemeProvider โ†’ AuthProvider<br/>โ†’ PostHogProvider* โ†’ MotionProvider* โ†’ CartProvider<br/><small>* dynamically imported, shop only</small>"]
    end

    subgraph admin["app/admin/layout.tsx + (protected)/layout.tsx"]
        admin_stack["QueryProvider โ†’ ThemeProvider โ†’ AuthProvider<br/>โ†’ AdminHeader / AdminNav / AdminBreadcrumb<br/><small>staff + MFA check, no PostHog</small>"]
    end

    pages["๐Ÿ“‘ Pages<br/><small>/, /producten, /producten/[slug] (SSR), /collectie/[slug],<br/>/teamkleding, /designer (?voor=team), /cart, /checkout,<br/>/offerte/[id], /account/*, /admin/*</small>"]
    components["๐Ÿงฉ Components<br/><small>header, products, product-detail, teamkleding, ProductDesigner (+ team/),<br/>checkout, designs, quotes, admin/*</small>"]
    hooks["๐Ÿช hooks/api/*<br/><small>TanStack Query hooks (useProducts, useCart,<br/>useDesigns, useAdminOrders, โ€ฆ)</small>"]
    api_client["๐Ÿ“ก lib/api/client.ts ยท adminClient.ts<br/><small>Axios, cookies + X-CSRFToken</small>"]
    backend_api["โšก Django API"]

    sentry_p --> shop & admin
    shop --> pages
    admin --> pages
    pages --> components --> hooks --> api_client --> backend_api

    style sentry_p fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style shop_stack fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style admin_stack fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style pages fill:#60a5fa,stroke:#3b82f6,color:#fff
    style components fill:#60a5fa,stroke:#3b82f6,color:#fff
    style hooks fill:#60a5fa,stroke:#3b82f6,color:#fff
    style api_client fill:#60a5fa,stroke:#3b82f6,color:#fff
    style backend_api fill:#10b981,stroke:#059669,color:#fff

4. Backend Architecture

The thirteen Django apps, the service layer they call and the Celery task groups.

flowchart TB
    subgraph api_layer["๐ŸŒ API layer"]
        drf["DRF routers<br/><small>public + /api/admin/ ยท drf-spectacular</small>"]
        allauth["django-allauth headless<br/><small>/_allauth/ ยท MFA</small>"]
    end

    subgraph apps["๐Ÿ“ฆ Django apps (13)"]
        products_app["products<br/><small>catalog, sellable variants, print zones, feed</small>"]
        designs_app["designs<br/><small>designs, review, collection, fonts, guest retention</small>"]
        orders_app["orders<br/><small>cart, team groups, checkout, orders, production</small>"]
        payments_app["payments<br/><small>Mollie, refunds, audit</small>"]
        pricing_app["pricing<br/><small>discounts, decoration methods</small>"]
        quotes_app["quotes<br/><small>OFF-YYYY-NNNNN</small>"]
        invoices_app["invoices<br/><small>INV-YYYY-NNNNN</small>"]
        users_app["users<br/><small>profiles, addresses, newsletter</small>"]
        core_app["core<br/><small>settings + switches, pages, audit, backups, health, reviews</small>"]
        informer_app["informer<br/><small>bookkeeping, off by default</small>"]
        more_apps["personalization ยท clipart ยท analytics"]
    end

    subgraph services["โšก Services"]
        svc["OrderService ยท team_groups ยท PaymentService ยท DesignRenderService<br/>pricing.decoration ยท informer.services ยท backup/monitor/discord services"]
    end

    subgraph tasks["โฐ Celery tasks"]
        t1["after payment: invoice + mail, print files, admin notify,<br/>Informer booking"]
        t2["scheduled: backups, monitoring, cart reminders, review requests,<br/>newsletter sync, Informer sweep, guest-design cleanup, website snapshot"]
        t3["signals: WebP variants, catalog import/export"]
    end

    drf --> apps
    allauth --> users_app
    apps --> services
    services --> tasks

    style drf fill:#10b981,stroke:#059669,color:#fff
    style allauth fill:#10b981,stroke:#059669,color:#fff
    style informer_app fill:#10b981,stroke:#059669,color:#fff
    style svc fill:#10b981,stroke:#059669,color:#fff
    style t1 fill:#f97316,stroke:#ea580c,color:#fff
    style t2 fill:#f97316,stroke:#ea580c,color:#fff
    style t3 fill:#f97316,stroke:#ea580c,color:#fff

5. Data Model Overview

The core commerce entities and how they relate; the full model list is in Database.

erDiagram
    User ||--o| UserProfile : has
    User ||--o{ CustomDesign : creates
    User ||--o| ShoppingCart : has
    User ||--o{ Order : places
    User ||--o{ Quote : requests

    Category ||--o{ Product : contains
    Product ||--o{ ProductVariant : has
    Product ||--o{ ProductColorImage : "images per color"
    Product ||--o{ ProductPrintZone : "print zones"
    ProductPrintZone }o--o| DecorationMethod : "priced by"

    CustomDesign }o--|| Product : "for"
    ShoppingCart ||--o{ CartItem : contains
    ShoppingCart |o--o{ OrderGroup : "team orders"
    OrderGroup }o--o| CustomDesign : "base_design"
    OrderGroup ||--o{ CartItem : "one line per piece"
    OrderGroup ||--o{ OrderItem : "one line per piece"
    CartItem }o--o| CustomDesign : "with design"

    Order ||--o{ OrderItem : contains
    OrderItem ||--o{ OrderItemPrintZone : "zone snapshots"
    Order ||--o{ Payment : "Mollie payments"
    Payment ||--o{ Refund : refunds
    Order |o--o| Invoice : invoice
    Order ||--o{ InformerBooking : "bookkeeping"
    Quote ||--o{ QuoteItem : contains
    Quote |o--o| Order : "converted to"

6. Checkout, Payment and Webhook

The checkout โ†’ Mollie โ†’ webhook sequence, including idempotency and the Celery work that follows a successful payment (OrderViewSet.checkout, webhook_handler, process_payment_status_update, orders/signals.py).

sequenceDiagram
    autonumber
    participant U as ๐Ÿ‘ค Customer
    participant F as ๐Ÿ–ฅ๏ธ Next.js
    participant A as โšก Django
    participant M as ๐Ÿ’ณ Mollie
    participant C as โฐ Celery

    U->>F: "Betalen" on /checkout
    F->>A: POST /api/orders/checkout/<br/>{address, payment_method, idempotency_key, terms_accepted}
    Note over A: throttle 5/min ยท select_for_update(cart)
    alt same idempotency_key and previous order still pending
        A-->>F: 200 existing order + payment_url
    else new checkout
        A->>A: OrderService.create_order_from_cart (status pending,<br/>stock not yet decremented, flags artwork review)
        A->>M: payments.create(amount, redirect + webhook URL)
        M-->>A: payment id + checkout_url
        A-->>F: 201 {order_id, order_number, order_token, payment_url}
    end
    F->>M: redirect customer to checkout_url
    U->>M: pays (iDEAL, or Mollie's own method screen when all_payment_methods_enabled)
    M->>A: POST /api/payments/webhook/ {id}
    A->>M: payments.get(id)  (POST body is never trusted)
    A->>A: lock Order ยท verify amount/currency ยท Payment.status โ† Mollie
    alt status paid and order pending
        A->>A: Order โ†’ paid, discount usage_count +1, stock decrement
        A-->>C: notify_admin_paid_order ยท send_shop_order_email ยท generate_invoice_and_email ยท generate_print_files
        C-->>C: informer.send_order after the invoice (if informer_mode โ‰  off)
    else expired / failed
        A-->>U: payment expired / failed email (retry link)
    end
    A-->>M: 200 (503 on a transient Mollie error โ†’ Mollie retries)
    M->>F: redirect to /checkout/bedankt
    F->>A: POST /api/orders/{id}/sync_payment/ (fallback if webhook is late)

Stock shortage after payment or an amount mismatch does not roll the payment back: the order stays paid with needs_attention = True, a note in admin_notes, a Sentry message and a Discord alert. monitoring.recover_incomplete_paid_orders (hourly at :45) re-schedules invoice, mail, notification or print files that are missing on paid orders.


7. Order Status Flow

Order.STATUS_CHOICES and the transitions OrderService.validate_order_state_transition allows. The pickup branch replaces shipped โ†’ delivered when fulfillment_method = 'pickup'; printing requires every design to have a print file.

stateDiagram-v2
    [*] --> pending : checkout
    pending --> paid : Mollie webhook (paid)
    pending --> cancelled : customer or staff cancels
    paid --> processing : staff
    paid --> refunded : full refund
    processing --> printing : print files ready
    processing --> cancelled
    printing --> shipped : fulfillment = shipping
    printing --> ready_for_pickup : fulfillment = pickup
    shipped --> delivered
    ready_for_pickup --> picked_up
    delivered --> [*]
    picked_up --> [*]
    cancelled --> [*]
    refunded --> [*]

Emails per transition (orders/signals.py): order confirmation on creation, paid mail with invoice PDF (Celery), shipping notification on shipped, status update on processing/printing/delivered/ready_for_pickup/picked_up, cancellation on cancelled. Staff can skip the status, shipping and cancellation mails with notify_customer: false on set_status / bulk-status. Outside this graph, the production board moves an order in paid, processing or printing to shipped (pickup: ready_for_pickup) once every item is shipped, without a customer email. Order numbers are ORD-YYYYMMDD-XXXXXX.


8. Payment and Refund Statuses

Mollie statuses mirrored on Payment and Refund; the order reacts only to the transitions shown.

stateDiagram-v2
    state Payment {
        [*] --> open : created at checkout
        open --> pending : customer at bank
        open --> paid
        pending --> paid : order โ†’ paid
        open --> expired : email, retry link
        pending --> failed : email, retry link
        open --> canceled
    }
    state Refund {
        [*] --> queued
        queued --> pending
        pending --> processing
        processing --> refunded : order โ†’ refunded when total covered
        pending --> failed : order back to paid, Discord alert
        pending --> canceled : order back to paid, Discord alert
    }

A customer can retry an expired or failed payment via POST /api/payments/retry/{order_id}/ (with order_token); get_or_create_open_payment reuses an open Mollie payment instead of creating a second one.


9. Design Review Flow

CustomDesign.STATUS_CHOICES and who moves a design between them. Review is advisory: it never blocks checkout, but an order with an unreviewed design gets needs_attention until staff approve the design.

stateDiagram-v2
    [*] --> draft : saved in the designer
    draft --> pending_review : customer POST /designs/{id}/request_approval/
    rejected --> pending_review : customer requests again
    pending_review --> approved : staff POST /admin/designs/{id}/approve/
    pending_review --> rejected : staff POST /admin/designs/{id}/reject/ (reason, optional mail)
    draft --> finalized : PATCH /designs/{id}/finalize/ (any status)
    approved --> finalized
    finalized --> [*]

Side effects: pending_review and approved/finalized send a customer email (designs/signals.py); approving also clears the artwork-review flag on orders that contain the design (resolve_artwork_review). in_production exists in STATUS_CHOICES but nothing in the code sets it. Publishing to the shop collection (POST /api/admin/designs/{id}/publish-to-collection/) sets is_collection_item rather than changing the status; the design is then sold as a ready-made article at /collectie/[slug].


10. Team Order Flow

One team order inside the normal order flow (v1.53, behind team_order_enabled): the product page collects quantities per size, the Designer in team mode fills the roster, and the cart holds the team as one OrderGroup with one line per piece.

sequenceDiagram
    autonumber
    participant U as ๐Ÿ‘ค Customer
    participant P as ๐Ÿ–ฅ๏ธ Product page
    participant D as ๐ŸŽจ Designer (team mode)
    participant A as โšก Django
    participant K as ๐Ÿ›’ Cart / checkout

    U->>P: "Voor een team", quantities per size
    P->>A: GET /api/settings/ (team_order_enabled), variants (sellable only)
    P->>D: /designer?product=โ€ฆ&voor=team&sizes=S:2,M:6
    D->>D: one roster row per shirt, paste a list from WhatsApp/Excel,<br/>name per side, duplicate numbers flagged
    D->>A: POST /api/designs/ (base design) ยท POST /api/cart/group-price/
    A-->>D: price for the whole group (print priced once)
    D->>A: POST /api/cart/groups/ {product_id, color_id, base_design_id, team_name, rows}
    A->>A: team_groups.validate_roster (โ‰ค 200 rows, no template product, stock)<br/>OrderGroup + one CartItem of 1 per row
    A-->>K: cart with groups[] โ†’ one card per team
    U->>K: "Aanpassen" โ†’ PATCH /api/cart/groups/{id}/ keeps design, names, team name
    K->>A: POST /api/orders/checkout/
    A->>A: OrderGroup detached from the cart, OrderItem.group per piece

The old wizard behind /team-order and the /namen-nummers page were removed in v1.53; both paths redirect to the landing page /teamkleding. In the admin the group shows with a names list as Excel (team-list).


11. Print Pricing per Zone

How the print cost of a design line is calculated (pricing/decoration.py, design_zone_unit_cost): per product print zone, by decoration method or a fixed zone price, with the legacy whole-design cost as fallback. Zones and the product photo live in a 600 ร— 800 reference frame (ZONE_REF_W/ZONE_REF_H); object coordinates are first scaled from the customer's canvasSize (300โ€“600 px) so a phone and a laptop give the same price.

flowchart TB
    design["CustomDesign<br/><small>design_json per view, canvasSize</small>"]
    zones["ProductPrintZone per view<br/><small>600 ร— 800 frame, px โ†’ cm via ProductViewScale</small>"]
    map["Map objects to zones<br/><small>scale canvasSize โ†’ 600 ร— 800, originX/originY,<br/>count colours, locations, area cmยฒ</small>"]
    method{"Zone has a<br/>DecorationMethod<br/>or fixed_price?"}
    dm["DecorationMethod tiers<br/><small>setup fees, per-colour, per-location,<br/>DecorationAreaTier ร— quantity</small>"]
    fixed["Fixed zone price"]
    legacy["Legacy design cost<br/><small>texts ร— design_text_price<br/>+ images ร— design_image_price<br/>+ TextColor surcharges</small>"]
    sum["print_unit_cost<br/><small>โ†’ CartItem.unit_price, OrderItem.printing_cost,<br/>OrderItemPrintZone snapshots</small>"]

    design --> map
    zones --> map
    map --> method
    method -->|"decoration method"| dm --> sum
    method -->|"fixed_price"| fixed --> sum
    method -->|"neither / no zones"| legacy --> sum

    style design fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style zones fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style sum fill:#10b981,stroke:#059669,color:#fff

12. CI/CD Pipeline

GitHub Actions: tests on every push and PR, staging deploy from staging, production deploy from a tag, docs site build.

flowchart TB
    subgraph triggers["๐ŸŽฏ Triggers"]
        push["Push / PR to staging or main"]
        tag["scripts/deploy-production.sh<br/><small>tags main, dispatches with tag input</small>"]
        docs_push["Push to main<br/><small>docs/backend/frontend paths</small>"]
    end

    subgraph ci["๐Ÿงช ci.yml"]
        be["backend-test<br/><small>Python 3.12, Postgres + Redis, flake8, pytest</small>"]
        fe["frontend-test ยท frontend-build<br/><small>Node 22, tsc, ESLint, Jest</small>"]
        e2e["Playwright smoke / visual / full / admin"]
        images["build-images.yml โ†’ GHCR"]
        deploy_staging["deploy โ†’ deploy-staging.yml<br/><small>rolling deploy, health check, rollback,<br/>Discord, then staging-perf-gate.yml (k6)</small>"]
    end

    prod["๐Ÿš€ deploy-production.yml<br/><small>reuse or build images, deploy checks, backup,<br/>migrations, rolling deploy, health, auto-rollback, Discord</small>"]
    docs["๐Ÿ“– docs.yml<br/><small>MkDocs + OpenAPI + Storybook + TypeDoc<br/>โ†’ Cloudflare Pages</small>"]

    push --> be & fe
    be & fe --> e2e --> images
    images -->|"staging branch only"| deploy_staging
    tag --> prod
    docs_push --> docs

    style be fill:#10b981,stroke:#059669,color:#fff
    style fe fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style e2e fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style images fill:#0ea5e9,stroke:#0284c7,color:#fff
    style deploy_staging fill:#0ea5e9,stroke:#0284c7,color:#fff
    style prod fill:#f97316,stroke:#ea580c,color:#fff
    style docs fill:#6b7280,stroke:#4b5563,color:#fff

Other workflows: backup-test.yml, ssl-renewal.yml, load-tests.yml, e2e-setup.yml, e2e-staging.yml (smoke test after every staging deploy), update-snapshots.yml, staging-auto-recreate.yml, report-zone-cm-conflicts.yml, feedback-retest-comment.yml, intake-ready.yml, voor-ivar-lijst.yml, dagplanning-waakhond.yml, dagbouw-bewaker.yml (auto-merge of day-plan PRs), websitecheck-discord.yml, enforce-pr-base.yml, dependabot-retarget.yml.


13. Deployment Topology

Production (www.freezedesign.nl, Hetzner CX43, docker-compose.prod.yml). Staging (staging.freezedesign.nl) has the same seven containers behind basic auth.

flowchart TB
    users["๐Ÿ‘ฅ Users"]

    subgraph github["๐Ÿ“ฆ GitHub"]
        actions["GitHub Actions"]
        ghcr["GHCR images<br/><small>backend, frontend</small>"]
    end

    subgraph server["๐Ÿ–ฅ๏ธ Hetzner VPS โ€” docker-compose.prod.yml"]
        nginx["๐Ÿ”€ nginx 1.31<br/><small>:80 โ†’ 301 https ยท :443 TLS<br/>apex + prod. โ†’ 301 www</small>"]
        frontend_c["โš›๏ธ frontend<br/><small>Next.js :3000</small>"]
        backend_c["๐Ÿ backend<br/><small>Gunicorn :8000</small>"]
        celery_c["โฐ celery<br/><small>mem_limit 768m, max-memory-per-child 256 MiB</small>"]
        beat_c["๐Ÿ“… celery-beat<br/><small>heartbeat healthcheck</small>"]
        postgres_c[("๐Ÿ˜ postgres:15")]
        redis_c[("โšก redis:7")]
        certbot["๐Ÿ”’ Let's Encrypt<br/><small>certbot webroot, ssl-renewal.yml</small>"]
    end

    subgraph ext["โ˜๏ธ External"]
        spaces["๐Ÿ“ฆ DO Spaces<br/><small>media + backups<br/>(+ rclone copy)</small>"]
        mollie["๐Ÿ’ณ Mollie"]
        informer["๐Ÿ“’ Informer"]
        sentry["๐Ÿ› Sentry"]
        discord["๐Ÿ’ฌ Discord"]
    end

    users --> nginx
    nginx --> frontend_c & backend_c
    nginx -.-> certbot
    frontend_c --> backend_c
    backend_c --> postgres_c & redis_c
    celery_c --> redis_c & postgres_c
    beat_c --> redis_c
    actions --> ghcr -->|"rolling deploy"| server
    backend_c --> mollie & sentry & spaces
    celery_c --> spaces & discord & informer

    style users fill:#6b7280,stroke:#4b5563,color:#fff
    style nginx fill:#009639,stroke:#007a2f,color:#fff
    style frontend_c fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style backend_c fill:#10b981,stroke:#059669,color:#fff
    style celery_c fill:#10b981,stroke:#059669,color:#fff
    style beat_c fill:#10b981,stroke:#059669,color:#fff
    style postgres_c fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style redis_c fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style ghcr fill:#6b7280,stroke:#4b5563,color:#fff
    style certbot fill:#f97316,stroke:#ea580c,color:#fff
    style spaces fill:#f97316,stroke:#ea580c,color:#fff
    style mollie fill:#f97316,stroke:#ea580c,color:#fff
    style informer fill:#f97316,stroke:#ea580c,color:#fff
    style sentry fill:#f97316,stroke:#ea580c,color:#fff
    style discord fill:#5865f2,stroke:#4752c4,color:#fff

14. API Endpoint Map

Public REST resources grouped by app; the admin API and auth live outside the public routers. Full list: API Reference.

flowchart LR
    subgraph api["โšก /api"]
        catalog["๐Ÿ“ฆ Catalog<br/><small>/products/ ยท /categories/ ยท /colors/<br/>/sizes/ ยท /variants/ ยท /collection/<br/>/feeds/google-shopping.xml</small>"]
        designs["๐ŸŽจ Designs<br/><small>/designs/ (+ price-preview,<br/>generate_preview, finalize, request_approval)<br/>/templates/ ยท /design-options/{colors,fonts}/<br/>/clipart-{categories,items}/ ยท /upload/image/</small>"]
        cart["๐Ÿ›’ Cart<br/><small>/cart/ (+ add, clear, apply-discount,<br/>reminder, restore, groups, group-price)<br/>/cart/items/{id}/ ยท /cart/groups/{id}/</small>"]
        orders["๐Ÿ“‹ Orders<br/><small>/orders/ ยท /orders/checkout/<br/>/orders/{id}/ (+ cancel, sync_payment)</small>"]
        payments["๐Ÿ’ณ Payments & invoices<br/><small>/payments/{issuers,webhook,retry/{id}}/<br/>/invoices/download/</small>"]
        quotes["๐Ÿ“„ Quotes<br/><small>/quotes/ (+ request, accept,<br/>convert, download)</small>"]
        account["๐Ÿ‘ค Account<br/><small>/auth/* ยท /addresses/ ยท /wishlist/<br/>/newsletter/*</small>"]
        core["โš™๏ธ Core<br/><small>/settings/ ยท /pages/{slug}/ ยท /postcode/<br/>/reviews/google/ ยท /health/</small>"]
        docs["๐Ÿ“š /schema/ ยท /docs/ ยท /redoc/"]
    end

    subgraph other["๐Ÿ” Outside the public routers"]
        allauth["/_allauth/browser/v1/<br/><small>login, signup, MFA, password reset</small>"]
        admin_api["/api/admin/*<br/><small>staff CRUD, analytics, settings, informer, health, backups</small>"]
        django_admin["/django-admin/<br/><small>Django admin, print-area editor, catalog manager</small>"]
    end

    style catalog fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style designs fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style cart fill:#10b981,stroke:#059669,color:#fff
    style orders fill:#10b981,stroke:#059669,color:#fff
    style payments fill:#f97316,stroke:#ea580c,color:#fff
    style quotes fill:#10b981,stroke:#059669,color:#fff
    style account fill:#6b7280,stroke:#4b5563,color:#fff
    style core fill:#6b7280,stroke:#4b5563,color:#fff
    style docs fill:#6b7280,stroke:#4b5563,color:#fff
    style allauth fill:#8b5cf6,stroke:#7c3aed,color:#fff

15. Frontend State Management

Where each kind of state lives in the frontend (no global store library is in use; zustand is in package.json but not imported anywhere). The former TeamOrderContext and NamesNumbersContext are gone: a team order is server state in the cart, and the roster being typed is Designer component state.

flowchart TB
    subgraph global["๐ŸŒ Client state (React Context, shop routes)"]
        auth_state["AuthContext<br/><small>user, login(), logout()</small>"]
        cart_state["CartContext<br/><small>cart, add/remove, totals</small>"]
        theme_state["ThemeContext<br/><small>light / dark / system</small>"]
    end

    subgraph server["๐Ÿ“ก Server state (TanStack Query, hooks/api/*)"]
        queries["useQuery: products, collection, designs,<br/>orders, quotes, settings, admin/*"]
        mutations["useMutation: cart (+ groups, group-price), designs,<br/>checkout, admin CRUD"]
        query_cache["QueryClient<br/><small>staleTime 5 min ยท gcTime 30 min</small>"]
    end

    subgraph local["๐Ÿ“ Local / browser"]
        canvas_state["Fabric.js canvas<br/><small>useCanvasHistory (undo/redo)</small>"]
        roster_state["Team roster (Designer state)<br/><small>rows from ?sizes=, pasted list, names per side</small>"]
        storage["localStorage<br/><small>theme, cookie consent, auth hint, drafts</small>"]
    end

    auth_state --> cart_state
    queries --> query_cache
    mutations --> query_cache
    theme_state --> storage
    canvas_state --> mutations
    roster_state -->|"POST /api/cart/groups/"| mutations

    style auth_state fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style cart_state fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style theme_state fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style canvas_state fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style roster_state fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style query_cache fill:#10b981,stroke:#059669,color:#fff

Quick Reference

Diagram Purpose
System Context The system and its external services
Request Path nginx โ†’ Next.js / Django, Celery, data stores
Frontend Provider stacks and layers
Backend Django apps, services, tasks
Data Model Core entities
Checkout Checkout โ†’ Mollie โ†’ webhook
Order Status Order state machine
Payment Status Payment and refund states
Design Review Design state machine
Team Order Product page โ†’ Designer team mode โ†’ OrderGroup
Print Pricing Zone-based print cost
CI/CD GitHub Actions workflows
Deployment Production / staging topology
API Map REST endpoints by resource
State Frontend state flow