Architecture Diagrams

Visual documentation of the Freeze Design webshop architecture, components, and workflows.

Color Legend

Color	Meaning
🟦 Blue	Frontend (Next.js/React)
🟩 Green	Backend (Django/DRF)
🟧 Orange	External Services
🟪 Purple	Database/Storage
⬜ Gray	Users/Actors

---

1. System Context Diagram

High-level overview showing the system and its external interactions.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#0d9488', 'primaryTextColor': '#fff', 'primaryBorderColor': '#0f766e', 'lineColor': '#64748b', 'secondaryColor': '#f1f5f9', 'tertiaryColor': '#fff'}}}%%
flowchart TB
    subgraph users[" 👥 Users "]
        customer["🛒 Customer<br/><small>Browse, Design, Order</small>"]
        teamManager["👔 Team Manager<br/><small>Bulk Orders</small>"]
        admin["⚙️ Admin<br/><small>Manage Catalog</small>"]
    end

    subgraph system["🏪 Freeze Design Webshop"]
        frontend["🖥️ Frontend<br/><small>Next.js 16</small>"]
        backend["⚡ Backend API<br/><small>Django REST</small>"]
    end

    subgraph external[" ☁️ External Services "]
        mollie["💳 Mollie<br/><small>Payments (iDEAL)</small>"]
        posthog["📊 PostHog<br/><small>Analytics</small>"]
        sentry["🐛 Sentry<br/><small>Error Tracking</small>"]
        do_spaces["📦 DO Spaces<br/><small>Media Storage</small>"]
        s3_backup["🗄️ AWS S3<br/><small>DB Backups</small>"]
        email["📧 Resend<br/><small>Email Notifications</small>"]
        discord["💬 Discord<br/><small>Alert Webhooks</small>"]
        uptimerobot["🔔 UptimeRobot<br/><small>Uptime Monitoring</small>"]
        cloudflare["☁️ Cloudflare<br/><small>CDN + WAF</small>"]
    end

    subgraph data[" 💾 Data Stores "]
        postgres[("🐘 PostgreSQL 15<br/><small>Primary DB</small>")]
        redis[("⚡ Redis 7<br/><small>Cache & Broker</small>")]
    end

    customer --> cloudflare
    teamManager --> cloudflare
    admin --> cloudflare
    cloudflare --> frontend

    frontend <--> backend
    backend --> mollie

    frontend --> posthog
    frontend --> sentry
    backend --> sentry
    backend --> do_spaces
    backend --> s3_backup
    backend --> email
    backend --> discord
    uptimerobot --> backend

    backend <--> postgres
    backend <--> redis

    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 posthog fill:#f97316,stroke:#ea580c,color:#fff
    style sentry fill:#f97316,stroke:#ea580c,color:#fff
    style do_spaces fill:#f97316,stroke:#ea580c,color:#fff
    style s3_backup fill:#f97316,stroke:#ea580c,color:#fff
    style email fill:#f97316,stroke:#ea580c,color:#fff
    style discord fill:#5865f2,stroke:#4752c4,color:#fff
    style uptimerobot fill:#f97316,stroke:#ea580c,color:#fff
    style cloudflare fill:#f97316,stroke:#ea580c,color:#fff
    style customer fill:#6b7280,stroke:#4b5563,color:#fff
    style teamManager fill:#6b7280,stroke:#4b5563,color:#fff
    style admin fill:#6b7280,stroke:#4b5563,color:#fff

---

2. Container Diagram

Services, applications, and their communication patterns.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#0d9488'}}}%%
flowchart TB
    subgraph browser["🌐 Browser"]
        spa["📱 Single Page App<br/><small>React 19 + Next.js 16</small><br/><small>TypeScript, Tailwind CSS</small>"]
        designer["🎨 Design Editor<br/><small>Fabric.js Canvas</small>"]
    end

    subgraph frontend_server["🖥️ Frontend Server :3000"]
        nextjs["⚛️ Next.js Server<br/><small>SSR + API Routes</small>"]
    end

    subgraph backend_server["⚡ Backend Server :8000"]
        django["🐍 Django API<br/><small>Gunicorn + DRF</small><br/><small>drf-spectacular</small>"]
        celery["⏰ Celery Worker<br/><small>Async Tasks</small>"]
        celery_beat["📅 Celery Beat<br/><small>Scheduled Tasks</small>"]
    end

    subgraph reverse_proxy["🔀 Nginx :80/:443"]
        nginx["Reverse Proxy<br/><small>SSL Termination</small>"]
    end

    subgraph data_layer["💾 Data Layer"]
        pg[("🐘 PostgreSQL 15<br/><small>Primary Database</small>")]
        redis_store[("⚡ Redis 7<br/><small>Cache & Broker</small>")]
    end

    subgraph storage["📦 External Storage"]
        do_spaces_c["🖼️ DO Spaces<br/><small>Media Files</small>"]
        s3_c["🗄️ AWS S3<br/><small>DB Backups</small>"]
    end

    spa --> nginx
    designer --> nginx
    nginx --> nextjs
    nginx --> django
    nextjs <-->|"REST API<br/>JSON + CSRF"| django

    django --> pg
    django --> redis_store
    django --> celery
    celery --> redis_store
    celery_beat --> redis_store
    celery --> do_spaces_c
    celery --> s3_c

    django --> do_spaces_c

    style spa fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style designer fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style nextjs fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style nginx fill:#009639,stroke:#007a2f,color:#fff
    style django fill:#10b981,stroke:#059669,color:#fff
    style celery fill:#10b981,stroke:#059669,color:#fff
    style celery_beat fill:#10b981,stroke:#059669,color:#fff
    style pg fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style redis_store fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style do_spaces_c fill:#f97316,stroke:#ea580c,color:#fff
    style s3_c fill:#f97316,stroke:#ea580c,color:#fff

---

3. Frontend Architecture

Next.js application structure with providers, contexts, and components.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#3b82f6'}}}%%
flowchart TB
    subgraph layout["📄 Root Layout"]
        subgraph providers["🔌 Providers Stack"]
            sentry_p["🐛 SentryProvider"]
            posthog_p["📊 PostHogProvider"]
            query_p["🔄 QueryProvider<br/><small>TanStack Query</small>"]
            theme_p["🎨 ThemeProvider"]
            auth_p["🔐 AuthProvider"]
            cart_p["🛒 CartProvider"]
            team_p["👥 TeamOrderProvider"]
        end
    end

    subgraph pages["📑 Pages (App Router)"]
        home["🏠 / <br/><small>Homepage</small>"]
        catalog_page["📦 /catalog<br/><small>Product Catalog</small>"]
        detail["🔍 /products/[slug]<br/><small>Product Detail</small>"]
        designer_page["🎨 /designer<br/><small>Design Editor</small>"]
        cart_page["🛒 /cart<br/><small>Shopping Cart</small>"]
        checkout["💳 /checkout<br/><small>Checkout</small>"]
        team["👥 /team-order<br/><small>Team Orders</small>"]
        orders["📋 /orders<br/><small>Order History</small>"]
        account_page["👤 /account<br/><small>Account Settings</small>"]
        designs_page["🎨 /designs<br/><small>Saved Designs</small>"]
        admin_page["⚙️ /admin<br/><small>Admin Dashboard</small>"]
    end

    subgraph components["🧩 Components (71 total)"]
        nav["🧭 Navigation"]
        product_comp["📦 ProductCard<br/>ProductGrid"]
        designer_comp["🎨 Designer<br/><small>Fabric.js Canvas</small>"]
        cart_comp["🛒 CartItem<br/>CartSummary"]
        form_comp["📝 Forms<br/>Inputs"]
    end

    subgraph hooks["🪝 Custom Hooks"]
        useProducts["useProducts"]
        useCart["useCart"]
        useDesign["useDesign"]
        useAuth["useAuth"]
    end

    subgraph api_client["📡 API Client"]
        axios_client["Axios Instance<br/><small>CSRF + Credentials</small>"]
    end

    sentry_p --> posthog_p --> query_p --> theme_p --> auth_p --> cart_p --> team_p

    team_p --> pages
    pages --> components
    components --> hooks
    hooks --> api_client
    api_client -->|"HTTP"| backend_api["⚡ Backend API"]

    style sentry_p fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style posthog_p fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style query_p fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style theme_p fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style auth_p fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style cart_p fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style team_p fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style home fill:#60a5fa,stroke:#3b82f6,color:#fff
    style catalog_page fill:#60a5fa,stroke:#3b82f6,color:#fff
    style detail fill:#60a5fa,stroke:#3b82f6,color:#fff
    style designer_page fill:#60a5fa,stroke:#3b82f6,color:#fff
    style cart_page fill:#60a5fa,stroke:#3b82f6,color:#fff
    style checkout fill:#60a5fa,stroke:#3b82f6,color:#fff
    style team fill:#60a5fa,stroke:#3b82f6,color:#fff
    style orders fill:#60a5fa,stroke:#3b82f6,color:#fff
    style account_page fill:#60a5fa,stroke:#3b82f6,color:#fff
    style designs_page fill:#60a5fa,stroke:#3b82f6,color:#fff
    style admin_page fill:#60a5fa,stroke:#3b82f6,color:#fff
    style backend_api fill:#10b981,stroke:#059669,color:#fff

---

4. Backend Architecture

Django application structure with apps and their responsibilities.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#10b981'}}}%%
flowchart TB
    subgraph api_layer["🌐 API Layer"]
        drf["Django REST Framework<br/><small>Serializers + Views</small>"]
        spectacular["drf-spectacular<br/><small>OpenAPI Docs</small>"]
    end

    subgraph apps["📦 Django Apps (10)"]
        users_app["👤 users<br/><small>Authentication</small><br/><small>Profiles, Addresses</small>"]
        products_app["📦 products<br/><small>Catalog</small><br/><small>Categories, Variants</small>"]
        designs_app["🎨 designs<br/><small>Custom Designs</small><br/><small>Templates, Fonts</small>"]
        orders_app["🛒 orders<br/><small>Cart & Orders</small><br/><small>Order Items</small>"]
        pricing_app["💰 pricing<br/><small>Discounts, Volume</small><br/><small>Team, Special Offers</small>"]
        clipart_app["🖼️ clipart<br/><small>SVG Assets</small>"]
        core_app["⚙️ core<br/><small>Settings, Pages</small><br/><small>Audit, Backups</small>"]
        payments_app["💳 payments<br/><small>Mollie Payments</small><br/><small>Refunds, Audit</small>"]
        invoices_app["🧾 invoices<br/><small>Invoice Generation</small><br/><small>Sequential Numbering</small>"]
        analytics_app["📊 analytics<br/><small>PostHog Events</small>"]
    end

    subgraph services["⚡ Services Layer"]
        design_service["Design Service<br/><small>Cost Calculation</small>"]
        order_service["Order Service<br/><small>Checkout Logic</small>"]
        pricing_service["Pricing Service<br/><small>Discount Rules</small>"]
        backup_service["Backup Service<br/><small>DB Backup/Restore</small>"]
        payment_service["Payment Service<br/><small>Mollie Integration</small>"]
    end

    subgraph tasks["⏰ Celery Tasks"]
        backup_task["Hourly DB Backup<br/><small>S3 Upload</small>"]
        email_task["Email Notifications<br/><small>Order Status</small>"]
        monitoring_task["Monitoring<br/><small>Disk, Payments</small>"]
    end

    drf --> apps
    spectacular --> drf
    apps --> services
    services --> tasks

    designs_app --> design_service
    orders_app --> order_service
    pricing_app --> pricing_service
    payments_app --> payment_service
    core_app --> backup_service

    style drf fill:#10b981,stroke:#059669,color:#fff
    style spectacular fill:#10b981,stroke:#059669,color:#fff
    style users_app fill:#34d399,stroke:#10b981,color:#000
    style products_app fill:#34d399,stroke:#10b981,color:#000
    style designs_app fill:#34d399,stroke:#10b981,color:#000
    style orders_app fill:#34d399,stroke:#10b981,color:#000
    style pricing_app fill:#34d399,stroke:#10b981,color:#000
    style clipart_app fill:#34d399,stroke:#10b981,color:#000
    style core_app fill:#34d399,stroke:#10b981,color:#000
    style payments_app fill:#34d399,stroke:#10b981,color:#000
    style invoices_app fill:#34d399,stroke:#10b981,color:#000
    style analytics_app fill:#34d399,stroke:#10b981,color:#000
    style design_service fill:#10b981,stroke:#059669,color:#fff
    style order_service fill:#10b981,stroke:#059669,color:#fff
    style pricing_service fill:#10b981,stroke:#059669,color:#fff
    style backup_service fill:#10b981,stroke:#059669,color:#fff
    style payment_service fill:#10b981,stroke:#059669,color:#fff
    style backup_task fill:#f97316,stroke:#ea580c,color:#fff
    style email_task fill:#f97316,stroke:#ea580c,color:#fff
    style monitoring_task fill:#f97316,stroke:#ea580c,color:#fff

---

5. Data Model Overview

Core database entities and their relationships.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#8b5cf6'}}}%%
erDiagram
    User ||--o| UserProfile : has
    User ||--o{ CustomDesign : creates
    User ||--o| ShoppingCart : has
    User ||--o{ Order : places

    Category ||--o{ Category : parent
    Category ||--o{ Product : contains
    Brand ||--o{ Product : owns

    Product ||--o{ ProductVariant : has
    Product }o--o{ Color : available_in
    Product }o--o{ Size : available_in

    ProductVariant ||--|| Product : belongs_to
    ProductVariant ||--|| Color : has
    ProductVariant ||--|| Size : has

    Color ||--o{ ProductColorImage : has_images

    CustomDesign ||--o| Product : for_product
    CustomDesign ||--o| ProductVariant : for_variant
    CustomDesign ||--o{ TeamNameList : has_members

    ShoppingCart ||--o{ CartItem : contains
    CartItem ||--o| ProductVariant : references
    CartItem ||--o| CustomDesign : has_design

    Order ||--o{ OrderItem : contains
    OrderItem ||--o| ProductVariant : references
    OrderItem ||--o| CustomDesign : has_design

    DiscountCode }o--o{ Order : applied_to
    VolumeDiscount ||--o{ VolumeDiscountTier : has_tiers
    VolumeDiscount ||--o| Product : for_product
    TeamDiscount ||--o{ Order : applied_to
    SpecialOffer ||--o| Product : for_product

    Order ||--o{ Payment : has_payment
    Payment ||--o{ Refund : has_refunds
    Payment ||--o{ PaymentAuditLog : has_audit
    Order ||--o| Invoice : has_invoice

    User ||--o{ ShippingAddress : has_addresses
    User ||--o{ WishlistItem : has_wishlist
    User ||--o{ BackupRecord : creates

    User {
        int id PK
        string email
        string password
        datetime created
    }

    PaymentAuditLog {
        int id PK
        string event_type
        string mollie_id
        json payload
        datetime created
    }

    BackupRecord {
        int id PK
        string filename
        string s3_url
        float size_mb
        string md5_checksum
        datetime created
    }

    Product {
        int id PK
        string sku
        string name
        string slug
        decimal base_price
        json print_positions
    }

    ProductVariant {
        int id PK
        string sku
        int stock_quantity
        decimal price_adjustment
        boolean is_active
    }

    CustomDesign {
        int id PK
        json design_json_front
        json design_json_back
        string status
        decimal calculated_cost
    }

    Payment {
        int id PK
        string mollie_id
        string status
        decimal amount
        datetime created
    }

    Invoice {
        int id PK
        string invoice_number
        int order_id FK
        decimal total
        datetime issued_date
    }

    Order {
        int id PK
        string order_number
        string status
        decimal total
        datetime created
    }

---

6. User Flow: Browse → Design → Checkout

Complete customer journey from browsing to order completion.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#0d9488'}}}%%
sequenceDiagram
    autonumber

    participant U as 👤 Customer
    participant F as 🖥️ Frontend
    participant B as ⚡ Backend
    participant DB as 💾 Database
    participant C as ⏰ Celery

    rect rgb(59, 130, 246, 0.1)
        Note over U,DB: 1️⃣ Browse Products
        U->>F: Visit /products
        F->>B: GET /api/products/
        B->>DB: Query products
        DB-->>B: Product list
        B-->>F: JSON response
        F-->>U: Display product grid
    end

    rect rgb(16, 185, 129, 0.1)
        Note over U,DB: 2️⃣ View Product Details
        U->>F: Click product card
        F->>B: GET /api/products/{slug}/
        B->>DB: Query product + variants
        DB-->>B: Product details
        B-->>F: Product with colors, sizes
        F-->>U: Show product page
    end

    rect rgb(139, 92, 246, 0.1)
        Note over U,C: 3️⃣ Create Design
        U->>F: Click "Start ontwerpen"
        F-->>U: Open Fabric.js canvas
        U->>F: Add text, images, colors
        F->>F: Local canvas editing
        U->>F: Click "Save Design"
        F->>B: POST /api/designs/
        B->>DB: Store design JSON
        B->>C: Generate preview task
        C->>DB: Store preview image
        B-->>F: Design ID + preview URL
        F-->>U: Show saved design
    end

    rect rgb(249, 115, 22, 0.1)
        Note over U,DB: 4️⃣ Add to Cart
        U->>F: Select size, quantity
        U->>F: Click "Add to cart"
        F->>B: POST /api/cart/add/
        B->>B: Calculate design cost
        B->>DB: Add CartItem
        DB-->>B: Updated cart
        B-->>F: Cart with totals
        F-->>U: Show cart badge
    end

    rect rgb(236, 72, 153, 0.1)
        Note over U,DB: 5️⃣ Checkout
        U->>F: Go to /checkout
        F->>B: GET /api/cart/
        B-->>F: Cart items + totals
        U->>F: Enter shipping info
        U->>F: Click "Place Order"
        F->>B: POST /api/orders/checkout/
        B->>B: Validate cart
        B->>B: Apply discounts
        B->>DB: Create Order + OrderItems
        B->>DB: Clear cart
        B-->>F: Order confirmation
        F-->>U: Show order success
    end

---

7. Design Cost Calculation Flow

How design pricing is calculated based on elements and colors.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#8b5cf6'}}}%%
flowchart TB
    subgraph input["📥 Design Input"]
        design["CustomDesign<br/><small>Fabric.js JSON</small>"]
    end

    subgraph parse["🔍 Parse Design"]
        front["Front View<br/><small>design_json_front</small>"]
        back["Back View<br/><small>design_json_back</small>"]
        left["Left View<br/><small>design_json_left</small>"]
        right["Right View<br/><small>design_json_right</small>"]
    end

    subgraph count["📊 Count Elements"]
        text_count["Text Elements<br/><small>i-text, textbox</small>"]
        image_count["Image Elements<br/><small>image, clipart</small>"]
    end

    subgraph colors["🎨 Color Analysis"]
        extract["Extract Unique Colors<br/><small>from text fills</small>"]
        lookup["Lookup TextColor<br/><small>price_modifier</small>"]
        surcharge["Color Surcharges<br/><small>special colors extra</small>"]
    end

    subgraph pricing["💰 Calculate Cost"]
        text_cost["Text Cost<br/><small>count × design_text_price</small>"]
        image_cost["Image Cost<br/><small>count × design_image_price</small>"]
        color_cost["Color Cost<br/><small>Σ surcharges</small>"]
    end

    subgraph total["📋 Total Design Cost"]
        sum["total = text_cost<br/>+ image_cost<br/>+ color_surcharges"]
    end

    design --> front & back & left & right
    front & back & left & right --> text_count & image_count
    front & back & left & right --> extract
    extract --> lookup --> surcharge

    text_count --> text_cost
    image_count --> image_cost
    surcharge --> color_cost

    text_cost & image_cost & color_cost --> sum

    style design fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style sum fill:#10b981,stroke:#059669,color:#fff
    style text_cost fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style image_cost fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style color_cost fill:#f97316,stroke:#ea580c,color:#fff

---

8. Team Order Flow

Bulk ordering workflow for teams and organizations.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#0d9488'}}}%%
sequenceDiagram
    autonumber

    participant TM as 👔 Team Manager
    participant F as 🖥️ Frontend
    participant B as ⚡ Backend
    participant DB as 💾 Database

    rect rgb(59, 130, 246, 0.1)
        Note over TM,DB: 1️⃣ Create Team Design Template
        TM->>F: Design team jersey template
        F->>B: POST /api/designs/
        B->>DB: Save template design
        B-->>F: Design ID
    end

    rect rgb(16, 185, 129, 0.1)
        Note over TM,DB: 2️⃣ Add Team Members
        TM->>F: Enter team roster
        Note right of F: Name, Number, Size<br/>per team member
        F->>B: POST /api/designs/{id}/add_team_names/
        B->>DB: Create TeamNameList entries
        B-->>F: Team roster saved
    end

    rect rgb(139, 92, 246, 0.1)
        Note over TM,DB: 3️⃣ Add All to Cart
        TM->>F: Click "Add team to cart"
        F->>B: POST /api/cart/add/ (bulk)
        loop For each team member
            B->>B: Calculate individual cost
            B->>DB: Create CartItem
        end
        B->>B: Check TeamDiscount eligibility
        B->>B: Apply volume discount
        B-->>F: Cart with team items
        F-->>TM: Show team order summary
    end

    rect rgb(249, 115, 22, 0.1)
        Note over TM,DB: 4️⃣ Checkout with Discount
        TM->>F: Proceed to checkout
        F->>B: POST /api/orders/checkout/
        B->>B: Apply TeamDiscount
        B->>DB: Create Order with all items
        B-->>F: Order with bulk pricing
        F-->>TM: Order confirmation
    end

---

9. CI/CD Pipeline

GitHub Actions workflow for testing, building, and deploying.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#0d9488'}}}%%
flowchart TB
    subgraph trigger["🎯 Triggers"]
        push_main_staging["Push to main"]
        pr["Pull Request"]
        manual["Manual Dispatch<br/><small>with version tag</small>"]
        push_main_docs["Push to main"]
    end

    subgraph ci["🧪 CI Pipeline (ci.yml)"]
        subgraph backend_test["🐍 Backend Tests"]
            py_setup["Setup Python 3.12"]
            pg_redis["Start PostgreSQL + Redis"]
            lint_be["Lint (flake8)"]
            migrate["Run Migrations"]
            pytest["pytest + Coverage"]
        end

        subgraph frontend_test["⚛️ Frontend Tests"]
            node_setup["Setup Node.js 20"]
            lint_fe["Lint (ESLint)"]
            jest["Jest Unit Tests"]
            playwright["Playwright E2E"]
        end

        subgraph docs_test["📚 Docs Tests"]
            mkdocs_build["Build MkDocs"]
        end
    end

    subgraph deploy_staging["🔄 Deploy Staging (auto)"]
        build_staging["🐳 Build Images"]
        push_ghcr_staging["📦 Push to GHCR"]
        rolling_staging["🔄 Rolling Deploy"]
        health_staging["❤️ Health Checks"]
        seed_staging["🌱 Import Seed Data"]
    end

    subgraph deploy_prod["🚀 Deploy Production (manual)"]
        docker_build["🐳 Build Docker Images"]
        ghcr_push["📦 Push to GHCR"]
        ssh_deploy["🔄 Rolling Deploy"]
        health_check["❤️ Health Checks"]
        rollback["↩️ Auto Rollback<br/><small>on failure</small>"]
        discord["📢 Discord Notify"]
    end

    subgraph docs_deploy["📖 Docs Deploy (docs.yml)"]
        build_mkdocs["Build MkDocs"]
        build_openapi["Build OpenAPI/Swagger"]
        build_storybook["Build Storybook"]
        build_typedoc["Build TypeDoc"]
        combine["Combine All Docs"]
        cloudflare["Deploy to Cloudflare Pages"]
    end

    push_main_staging --> ci
    push_main_staging --> deploy_staging
    pr --> ci
    push_main_docs --> docs_deploy

    manual --> deploy_prod

    ci --> backend_test & frontend_test & docs_test

    py_setup --> pg_redis --> lint_be --> migrate --> pytest
    node_setup --> lint_fe --> jest --> playwright

    build_staging --> push_ghcr_staging --> rolling_staging --> health_staging --> seed_staging

    docker_build --> ghcr_push --> ssh_deploy --> health_check --> discord
    health_check -.->|"failure"| rollback

    build_mkdocs & build_openapi & build_storybook & build_typedoc --> combine --> cloudflare

    style push_main_staging fill:#6b7280,stroke:#4b5563,color:#fff
    style push_main_docs fill:#6b7280,stroke:#4b5563,color:#fff
    style pr fill:#6b7280,stroke:#4b5563,color:#fff
    style manual fill:#f97316,stroke:#ea580c,color:#fff
    style pytest fill:#10b981,stroke:#059669,color:#fff
    style playwright fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style docker_build fill:#0ea5e9,stroke:#0284c7,color:#fff
    style build_staging fill:#0ea5e9,stroke:#0284c7,color:#fff
    style cloudflare fill:#f97316,stroke:#ea580c,color:#fff
    style discord fill:#5865f2,stroke:#4752c4,color:#fff
    style rollback fill:#dc2626,stroke:#b91c1c,color:#fff

---

10. Deployment Architecture

Production environment topology.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#0d9488'}}}%%
flowchart TB
    subgraph internet["🌐 Internet"]
        users["👥 Users"]
        cdn["☁️ Cloudflare<br/><small>CDN + WAF</small>"]
    end

    subgraph github["📦 GitHub"]
        repo["Repository"]
        ghcr["Container Registry<br/><small>GHCR</small>"]
        actions["GitHub Actions"]
    end

    subgraph server["🖥️ Hetzner CX33 (8GB RAM)"]
        subgraph docker["🐳 Docker Compose (7 containers)"]
            nginx["🔀 Nginx<br/><small>Reverse Proxy</small><br/><small>:80, :443</small>"]
            frontend_c["⚛️ Frontend<br/><small>Next.js</small><br/><small>:3000</small>"]
            backend_c["🐍 Backend<br/><small>Django + Gunicorn</small><br/><small>:8000</small>"]
            celery_c["⏰ Celery Worker<br/><small>Async Tasks</small>"]
            celery_beat_c["📅 Celery Beat<br/><small>Scheduled Tasks</small>"]
            postgres_c[("🐘 PostgreSQL 15<br/><small>:5432</small>")]
            redis_c[("⚡ Redis 7<br/><small>:6379</small>")]
        end

        letsencrypt["🔒 Let's Encrypt<br/><small>SSL Certificates</small>"]
    end

    subgraph external["☁️ External Services"]
        s3_ext["🗄️ AWS S3<br/><small>DB Backups</small>"]
        do_spaces_ext["📦 DO Spaces<br/><small>Media Storage</small>"]
        sentry_ext["🐛 Sentry"]
        posthog_ext["📊 PostHog"]
        mollie_ext["💳 Mollie<br/><small>Payments</small>"]
        discord_ext["💬 Discord<br/><small>Alerts</small>"]
    end

    users --> cdn --> nginx
    nginx --> frontend_c
    nginx --> backend_c
    nginx --> letsencrypt

    frontend_c <--> backend_c
    backend_c --> postgres_c
    backend_c --> redis_c
    backend_c --> celery_c
    celery_c --> redis_c
    celery_beat_c --> redis_c

    actions --> ghcr
    ghcr --> docker

    backend_c --> sentry_ext
    frontend_c --> sentry_ext
    frontend_c --> posthog_ext
    backend_c --> s3_ext
    backend_c --> do_spaces_ext
    backend_c --> mollie_ext
    backend_c --> discord_ext

    style users fill:#6b7280,stroke:#4b5563,color:#fff
    style cdn fill:#f97316,stroke:#ea580c,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 celery_beat_c fill:#10b981,stroke:#059669,color:#fff
    style postgres_c fill:#8b5cf6,stroke:#7c3aed,color:#fff
    style redis_c fill:#dc2626,stroke:#b91c1c,color:#fff
    style ghcr fill:#6b7280,stroke:#4b5563,color:#fff
    style letsencrypt fill:#f97316,stroke:#ea580c,color:#fff

---

11. API Endpoint Map

REST API organized by resource.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#10b981'}}}%%
flowchart LR
    subgraph api["⚡ /api"]
        subgraph products_api["📦 Products"]
            p1["GET /products/"]
            p2["GET /products/{slug}/"]
            p3["GET /categories/"]
            p4["GET /categories/tree/"]
            p5["GET /colors/"]
            p6["GET /sizes/"]
            p7["GET /variants/"]
        end

        subgraph designs_api["🎨 Designs"]
            d1["GET /designs/"]
            d2["POST /designs/"]
            d3["GET /designs/{id}/"]
            d4["PATCH /designs/{id}/"]
            d5["DELETE /designs/{id}/"]
            d6["POST /designs/{id}/add_team_names/"]
            d7["POST /designs/{id}/generate_preview/"]
            d8["PATCH /designs/{id}/finalize/"]
        end

        subgraph cart_api["🛒 Cart"]
            c1["GET /cart/"]
            c2["POST /cart/add/"]
            c3["PATCH /cart/items/{id}/"]
            c4["DELETE /cart/items/{id}/"]
            c5["POST /cart/clear/"]
        end

        subgraph orders_api["📋 Orders"]
            o1["GET /orders/"]
            o2["GET /orders/{id}/"]
            o3["POST /orders/checkout/"]
        end

        subgraph clipart_api["🖼️ Clipart"]
            cl1["GET /clipart/categories/"]
            cl2["GET /clipart/items/"]
        end

        subgraph payments_api["💳 Payments"]
            pay1["POST /payments/webhook/"]
        end

        subgraph health_api["❤️ Health"]
            h1["GET /health/"]
        end

        subgraph docs_api["📚 Docs"]
            doc1["GET /schema/"]
            doc2["GET /docs/"]
            doc3["GET /redoc/"]
        end
    end

    subgraph other_routes["🔐 Other Routes"]
        allauth["/_allauth/<br/><small>Headless Auth (login, register, MFA)</small>"]
        admin_api["/api/admin/<br/><small>Admin CRUD endpoints</small>"]
        django_admin["/django-admin/<br/><small>Django Admin + 2FA</small>"]
    end

    style p1 fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style d2 fill:#10b981,stroke:#059669,color:#fff
    style c2 fill:#10b981,stroke:#059669,color:#fff
    style o3 fill:#10b981,stroke:#059669,color:#fff
    style pay1 fill:#f97316,stroke:#ea580c,color:#fff
    style allauth fill:#8b5cf6,stroke:#7c3aed,color:#fff

---

12. State Management

How application state flows through the frontend.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#3b82f6'}}}%%
flowchart TB
    subgraph global["🌍 Global State (React Context + Zustand)"]
        auth_state["🔐 AuthContext<br/><small>user, loading</small><br/><small>login(), logout()</small>"]
        cart_state["🛒 CartContext<br/><small>cart, items</small><br/><small>add(), remove()</small>"]
        team_state["👥 TeamOrderContext<br/><small>members, design</small>"]
        theme_state["🎨 ThemeContext<br/><small>theme: light/dark</small>"]
    end

    subgraph server["📡 Server State (TanStack Query)"]
        products_query["useQuery: products"]
        design_query["useQuery: designs"]
        order_query["useQuery: orders"]
        mutation["useMutation:<br/><small>create, update, delete</small>"]
    end

    subgraph local["📍 Local State (useState / Zustand stores)"]
        form_state["Form inputs"]
        modal_state["Modal visibility"]
        canvas_state["🎨 Fabric.js Canvas<br/><small>Design editor state</small>"]
    end

    subgraph cache["💾 Cache Layer"]
        query_cache["React Query Cache<br/><small>5 min stale time</small>"]
        local_storage["localStorage<br/><small>Theme, preferences</small>"]
    end

    auth_state --> cart_state
    cart_state --> team_state

    products_query --> query_cache
    design_query --> query_cache
    order_query --> query_cache

    theme_state --> local_storage
    canvas_state --> mutation --> design_query

    style auth_state fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style cart_state fill:#3b82f6,stroke:#1d4ed8,color:#fff
    style team_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 query_cache fill:#10b981,stroke:#059669,color:#fff

---

Quick Reference

Diagram	Purpose
System Context	High-level system overview
Container	Services and communication
Frontend	Next.js structure
Backend	Django apps
Data Model	Database entities
User Flow	Customer journey
Design Cost	Pricing logic
Team Order	Bulk ordering
CI/CD	Deployment pipeline
Deployment	Production topology
API Map	REST endpoints
State	Frontend state flow