Architecture¶
This section provides an overview of the Freeze Design webshop architecture, including system design decisions and component interactions.
System Overview¶
The Freeze Design webshop follows a decoupled architecture: a Next.js storefront and staff interface talk to a Django REST API, which owns the data and delegates asynchronous work to Celery.
Request path from the browser to the two runtimes and the data stores (Celery runs as a separate worker and beat container):
flowchart TB
users["👥 Users"]
nginx["🔀 Nginx 1.31<br/><small>:80 / :443, TLS</small>"]
frontend["⚛️ Next.js Frontend<br/><small>:3000</small>"]
backend["🐍 Django REST API<br/><small>:8000 (Gunicorn)</small>"]
postgres[("🐘 PostgreSQL 15<br/><small>:5432</small>")]
redis[("⚡ Redis 7<br/><small>:6379</small>")]
celery["⏰ Celery worker + beat"]
users --> nginx
nginx -->|"/, /_next/static/"| frontend
nginx -->|"/api/, /_allauth/, /django-admin/"| backend
frontend -->|"server-side fetch"| backend
backend --> postgres
backend --> redis
backend -.->|"enqueue"| celery
celery --> redis
celery --> postgres
style frontend fill:#3b82f6,stroke:#1d4ed8,color:#fff
style backend fill:#10b981,stroke:#059669,color:#fff
style celery fill:#10b981,stroke:#059669,color:#fff
style postgres fill:#8b5cf6,stroke:#7c3aed,color:#fff
style redis fill:#8b5cf6,stroke:#7c3aed,color:#fff
style nginx fill:#009639,stroke:#007a2f,color:#fff
style users fill:#6b7280,stroke:#4b5563,color:#fff
Technology Versions¶
| Layer | Technology | Version |
|---|---|---|
| Backend framework | Django | 6.1.2 |
| API | Django REST Framework | 3.18.3 |
| Async tasks | Celery | 5.6.3 |
| Backend runtime | Python (Docker image python:3.14-slim) |
3.14 |
| Frontend framework | Next.js | 16.4.2 |
| UI library | React | 19.3.1 |
| Frontend runtime | Node.js (Docker image node:26-alpine) |
26 |
| Styling | Tailwind CSS | 4 |
| Server state | TanStack Query | 5.104 |
| Design canvas | Fabric.js | 7.4.0 |
| Payments | mollie-api-python | ≥ 4.0.0 |
| PDF (invoices, quotes, reports) | WeasyPrint | ≥ 70.0 |
| WSGI server | gunicorn | 26.2.0 |
| Database | PostgreSQL (postgres:15-alpine) |
15 |
| Cache & broker | Redis (redis:7-alpine) |
7 |
| Reverse proxy | nginx (nginx:1.31.6-alpine) |
1.31.6 |
CI versions differ from runtime versions
.github/workflows/ci.yml pins Python 3.12 and Node 22 for tests; the
Docker runtime images use Python 3.14 and Node 26. Both are intentional.
Sections¶
- Overview - High-level architecture, request flow and deployment
- Visual Diagrams - Architecture, data and workflow diagrams (Mermaid)
- Backend (Django) - Django app structure, services and Celery tasks
- Frontend (Next.js) - Routes, providers, state and the product designer
- Database - Data models and relationships
Quick Links¶
| Diagram | Description |
|---|---|
| System Context | The system and its external services |
| Checkout → Mollie → Webhook | How an order gets paid |
| Order Status Flow | Order.STATUS_CHOICES and allowed transitions |
| Design Review | Customer request → staff approval |
| Team Order | Product page → Designer team mode → OrderGroup in the cart |
| CI/CD Pipeline | GitHub Actions workflows |
| Deployment | Production / staging topology |