Skip to content

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

  1. 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.
  2. Component-based - Reusable React components organised by feature.
  3. Type-safe - TypeScript throughout the frontend; frontend/types/api.generated.ts is generated from the OpenAPI schema (npm run generate:api-types).
  4. 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.
  5. Dutch product - All customer-facing text is Dutch; routes are Dutch (/producten, /collectie, /teamkleding, /offerte).
  6. Features behind switches - Customer-facing features ship off by default behind a SiteSettings flag 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) and app/admin/(protected)/ (staff admin, MFA-enforced), plus app/admin/login, app/api/health, robots.ts and sitemap.ts.
  • Product detail pages (/producten/[slug]) are server components with generateMetadata, so title, description and og: tags are in the first HTML. Site settings and CMS pages are loaded server-side via lib/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 one OrderGroup.
  • 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

  1. 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.
  2. Client code sends session-aware requests (cookies + X-CSRFToken) to Django under /api/, or to django-allauth under /_allauth/, through the Axios clients in lib/api/client.ts and lib/api/adminClient.ts.
  3. View sets, serializers and service modules validate the request, apply business rules and read or write models in PostgreSQL.
  4. Redis serves cache and session data and is the Celery broker; anything that should not run inline is enqueued (usually with transaction.on_commit).
  5. 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 behind DEBUG=False.
  • CSRF protection for mutations (host-only CSRF cookie, X-CSRFToken header).
  • 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.ts strips 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's guest_email is 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.nl and prod.freezedesign.nl redirect to www). Runs tagged releases from main; v1.60 is live (2026-11-06). Deployed with scripts/deploy-production.sh, which tags main and starts deploy-production.yml (workflow_dispatch with a tag input) on a Hetzner CX43.
  • Staging - https://staging.freezedesign.nl (HTTP basic auth, orange banner with the deployed SHA). Deployed by the deploy job of ci.yml on every push to staging, 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.