Architecture Overview¶
Freeze Design is a custom apparel e-commerce platform with an integrated product designer. A Next.js storefront and staff interface call a Django REST API; Django persists commerce data in PostgreSQL, uses Redis for caching, sessions and Celery coordination, and delegates payments, email, object storage, analytics and error reporting to external services. In deployed environments every browser request enters through nginx and returns HTML, JSON, media or a generated PDF.
Design Principles¶
- API-first - All functionality is exposed via the REST API under
/api/; the Django admin at/django-admin/is a fallback, the day-to-day admin is a Next.js app. - Component-based - Reusable React components organised by feature.
- Type-safe - TypeScript throughout the frontend;
frontend/types/api.generated.tsis generated from the OpenAPI schema (npm run generate:api-types). - Stateless web tier, async side effects - Gunicorn workers hold no state; slow work (invoice PDFs, print files, mails after payment, backups, WebP variants) runs in Celery.
- Dutch product - All customer-facing text is Dutch; routes are Dutch
(
/producten,/collectie,/teamkleding,/offerte). - Features behind switches - Customer-facing features ship off by default
behind a
SiteSettingsflag that Eefje flips in the admin (team orders, all Mollie methods, cart reminder, review request, WhatsApp buttons, Informer).
System Components¶
Request path and the services the backend depends on (external services are described per concern below):
flowchart LR
user["Customer or staff browser"] --> nginx["nginx<br/><small>TLS, routing, static/media</small>"]
nginx -->|"/, /_next/"| frontend["Next.js 16<br/><small>SSR + client</small>"]
nginx -->|"/api/, /_allauth/, /django-admin/"| api["Django 6 + DRF<br/><small>Gunicorn</small>"]
frontend -->|"server-side fetch"| api
api --> postgres[("PostgreSQL 15")]
api --> redis[("Redis 7<br/><small>cache, sessions, broker</small>")]
api -.->|"enqueue"| celery["Celery worker + beat"]
celery --> redis
celery --> postgres
api --> mollie["Mollie"]
api --> resend["Resend"]
api --> spaces["DO Spaces<br/><small>media</small>"]
celery --> informer["Informer<br/><small>bookkeeping, off by default</small>"]
celery --> backups["S3-compatible bucket<br/><small>DB backups</small>"]
celery --> discord["Discord webhooks"]
Frontend (Next.js)¶
Next.js 16.4.2 with React 19.3.1 and the App Router.
- Two route groups:
app/(shop)/(storefront, account) andapp/admin/(protected)/(staff admin, MFA-enforced), plusapp/admin/login,app/api/health,robots.tsandsitemap.ts. - Product detail pages (
/producten/[slug]) are server components withgenerateMetadata, so title, description andog:tags are in the first HTML. Site settings and CMS pages are loaded server-side vialib/loadSiteData.ts. - Fabric.js 7 canvas for the product designer (
components/ProductDesigner/), with a team mode that fills one roster row per shirt and puts the whole team in the cart as oneOrderGroup. - React Context for client state (auth, cart, theme); TanStack Query 5 for server
state (
hooks/api/). - Sentry (
@sentry/nextjs) on client, server and edge; PostHog only on shop routes (never in the admin).
See Frontend.
Backend (Django REST Framework)¶
Django 6.1.2 + DRF 3.18.3, fourteen apps under backend/apps/: agent_api, analytics,
clipart, core, designs, informer, invoices, orders, payments,
personalization, pricing, products, quotes, users.
- Session-based auth through django-allauth headless (
/_allauth/), MFA (TOTP + recovery codes) enforced for staff, django-axes lockout. - OpenAPI schema via drf-spectacular (
/api/schema/,/api/docs/,/api/redoc/). - Celery 5.6 with a Redis broker for backups, monitoring, post-payment work, WebP generation, cart reminders, review requests, newsletter sync, Informer bookings, guest-design and guest-cart cleanup, healthchecks.io pings, quote-assistant requests and the weekly website snapshot.
- PostgreSQL 15; categories use MPTT.
See Backend.
External services¶
| Concern | Service | Where it is wired |
|---|---|---|
| Payments (iDEAL and other Mollie methods) | Mollie | apps/payments (PaymentService, webhook) |
| Transactional email + newsletter contacts | Resend via django-anymail; subscribers via the Resend /contacts API (RESEND_SEGMENT_ID optional) |
apps/core/email, apps/users/newsletter.py |
| Bookkeeping (off by default) | Informer: a paid order becomes a sales invoice with the customer as relation (informer_mode = off, preview or live) |
apps/informer (client.py, services.py, tasks.py) |
| Reviews | Google Places API (GOOGLE_PLACES_API_KEY, SiteSettings.google_place_id) |
apps/core/views.py (GoogleReviewsView) |
| Product feed | Google Merchant Center / Meta / Pinterest pull GET /api/feeds/google-shopping.xml |
apps/products/feeds.py |
| Media storage | DigitalOcean Spaces (S3 API, USE_SPACES=True) |
config/settings.py STORAGES |
| Database backups | S3-compatible bucket (BACKUP_S3_*, DO Spaces or AWS) |
apps/core/services/backup_service.py |
| Error tracking | Sentry (backend sentry-sdk, frontend @sentry/nextjs) |
config/settings.py, frontend/instrumentation*.ts |
| Product analytics | PostHog (EU), proxied through /ingest/ |
frontend/instrumentation-client.ts, lib/posthog.ts |
| Ops notifications | Discord webhooks (DISCORD_WEBHOOK_URL, BACKUP_DISCORD_WEBHOOK), and since v1.59 also the self-hosted ntfy on the Freeze AI VM (NTFY_URL) |
apps/core/services/discord_*.py, notify_service.py, CI (scripts/notify-ntfy.sh) |
| Heartbeat monitoring | healthchecks.io (HEALTHCHECK_PING_URL, NTFY_HEARTBEAT_PING_URL) |
apps/core/services/healthchecks.py |
| AI agent (quote assistant) | Freeze AI VM over the tailnet: it reads /api/agent/v1/ and the shop asks it for a draft per quote request (FREEZE_AI_AGENT_URL) |
apps/agent_api |
| Uptime | none yet: an external monitor on /api/health/ is an open todo (externe-uptime-monitor) |
— |
| Website figures in the admin | PostHog + Sentry read-only APIs | apps/analytics/website.py |
Request Flow¶
- The browser renders a storefront or admin route from the Next.js App Router. Server components fetch what they need from the API during the render.
- Client code sends session-aware requests (cookies +
X-CSRFToken) to Django under/api/, or to django-allauth under/_allauth/, through the Axios clients inlib/api/client.tsandlib/api/adminClient.ts. - View sets, serializers and service modules validate the request, apply business rules and read or write models in PostgreSQL.
- Redis serves cache and session data and is the Celery broker; anything that should
not run inline is enqueued (usually with
transaction.on_commit). - The API returns JSON or a file response; the frontend updates TanStack Query caches or React Context and re-renders.
Checkout and Payment Flow¶
Checkout creates the order and the Mollie payment in one transaction; the order only
becomes paid through the webhook, which re-fetches the status from Mollie:
sequenceDiagram
participant U as Customer
participant F as Next.js
participant A as Django API
participant M as Mollie
participant C as Celery
U->>F: Place order (/checkout)
F->>A: POST /api/orders/checkout/ (+ idempotency_key)
A->>A: Lock cart, create Order (pending)
A->>M: Create payment
M-->>A: checkout_url
A-->>F: 201 {order_id, order_token, payment_url}
F->>M: Redirect customer
M->>A: POST /api/payments/webhook/ {id}
A->>M: GET payment status (never trusts the POST body)
A->>A: Order → paid, stock decrement, discount usage
A-->>C: notify admin, invoice PDF + mail, print files
U->>F: Back on /checkout/bedankt
F->>A: POST /api/orders/{id}/sync_payment/ (fallback if webhook is late)
Details: Checkout, payment and webhook and Order status flow.
Security Architecture¶
- HTTPS enforced by nginx (Let's Encrypt via certbot), HSTS with preload,
SECURE_*settings behindDEBUG=False. - CSRF protection for mutations (host-only CSRF cookie,
X-CSRFTokenheader). - Rate limiting: DRF anon/user throttles plus scoped throttles for uploads, checkout (5/min), payment retry (3/min), the Mollie webhook (120/min), verification mail, newsletter sign-up and anonymous design creation (30/hour and 100/day per IP).
- Content Security Policy via django-csp 4 (strict in production, report-only switch).
- Staff MFA enforcement (
StaffMFAEnforcementMiddleware, allauth MFA: TOTP + recovery codes); login lockout via django-axes (5 attempts, 1 hour), using the client IP that nginx adds (TRUSTED_PROXY_COUNT = 1). - Mollie webhook never trusts the POST body; the paid amount and currency are verified against the order total before the order is marked paid.
- Design preview uploads are validated as PNG; vector uploads (.ai/.eps/.pdf) are rasterised server-side.
- Privacy:
lib/privacyUrl.tsstrips password-reset keys, verification keys and order ids from URLs before they reach PostHog or Sentry. Guest designs without an order are deleted after 90 days and a guest'sguest_emailis wiped after 12 months (apps/designs/retention.py, daily Celery tasks).
Deployment Architecture¶
Two environments, each a Docker Compose stack (nginx, frontend, backend, celery, celery-beat, postgres, redis) on its own Hetzner VPS:
- Production -
https://www.freezedesign.nl(live since 2026-09-30;freezedesign.nlandprod.freezedesign.nlredirect to www). Runs tagged releases frommain; v1.60 is live (2026-11-06). Deployed withscripts/deploy-production.sh, which tagsmainand startsdeploy-production.yml(workflow_dispatchwith ataginput) on a Hetzner CX43. - Staging -
https://staging.freezedesign.nl(HTTP basic auth, orange banner with the deployed SHA). Deployed by thedeployjob ofci.ymlon every push tostaging, after tests are green.
Production serves a single domain with the API under /api (no api. subdomain),
the same as staging. See the Deployment Guide and the
Deployment topology diagram.
DNS and CDN
DNS for freezedesign.nl (apex, www, prod, staging) is hosted at the
registrar (Openprovider) and points straight at the VPSes; there is no CDN or
proxy in front of the shop. infrastructure/cloudflare-cdn.md is a design for a
possible later move. The developer documentation site itself is deployed to
Cloudflare Pages by docs.yml.
Key Abstractions¶
| Area | Location | Responsibility |
|---|---|---|
| Django URL composition | backend/config/urls.py |
Mounts the DRF routers (public + admin/), allauth, payments, invoices, newsletter, feeds, health, schema and the Django admin. |
| Django settings | backend/config/settings.py |
Environment-specific application, security, storage, cache, Celery, email and monitoring configuration. |
| Celery beat schedule | backend/config/celery.py |
Periodic tasks (backups, monitoring, reminders, newsletter, Informer, guest-design cleanup, website snapshot), in Europe/Amsterdam. |
| Commerce services | backend/apps/*/services.py |
OrderService, PaymentService, invoice/quote generation, design rendering, pricing, Informer bookings. |
| Team orders | backend/apps/orders/team_groups.py, OrderGroup |
Validates a roster (up to 200 rows), prices the print once over the group, one CartItem/OrderItem per piece. |
| Zone-based print pricing | backend/apps/pricing/decoration.py |
Prices a design per print zone and decoration method (design_zone_unit_cost) in the 600 × 800 reference frame; object coordinates are scaled from the customer's canvasSize. |
| API serializers and views | backend/apps/*/serializers.py, views.py, admin_views.py |
Request/response contracts for the shop and the admin API. |
| Frontend API layer | frontend/lib/api/ |
Axios clients for storefront (client.ts) and admin (adminClient.ts). |
| Query hooks | frontend/hooks/api/ |
TanStack Query hooks per resource (useProducts, useCart, useAdminOrders, ...). |
| Product designer | frontend/components/ProductDesigner/ |
Fabric.js canvas editing, print zones, previews, design review, cart integration and the team mode (components/team/, lib/teamOrder/). |
Directory Structure Rationale¶
backend/ Django project, domain apps, migrations, tests, management commands
frontend/ Next.js routes, UI components, API clients, contexts, hooks, E2E tests
docs/docs/ MkDocs source grouped by architecture, guides, API, runbooks, QA
scripts/ Setup, release, backup, deployment, health and maintenance automation
loadtests/ k6 scenarios and recorded baseline results
nginx/ Reverse-proxy configuration for staging and production
.github/workflows/ CI, docs, security, backup, deployment and planning automation
.planning/ Internal todos, day plans and weekly reports (not Eefje-visible)
Backend domain boundaries follow Django apps, while frontend boundaries separate routes from reusable components, remote-data hooks and client state. Operational assets live at repository level because they coordinate both runtimes.