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.tsinit,PostHogProvider$pageview,lib/posthog.tstyped events; requests go through the/ingest/rewrite innext.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 pullGET /api/feeds/google-shopping.xmlthemselves. WhatsApp is only awa.melink 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
paidwithneeds_attention = True, a note inadmin_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-orderand the/namen-nummerspage 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 |