workspace.dsl

workspace "PrepFlow" "C4 architecture model for Thai Joint PH pre-order, payment verification, and kitchen-prep automation." {

    model {
        customer = person "Customer" "Browses the menu, places pre-orders, uploads receipt proof, and tracks fulfillment."
        admin = person "Thai Joint PH Admin" "Manages the catalog, verifies receipt uploads, updates order status, and prepares procurement lists."

        paymentApps = softwareSystem "External Payment Apps" "GCash, Maya, and bank applications. Payment happens outside PrepFlow." "External System"
        couriers = softwareSystem "External Couriers" "Lalamove and Grab are booked manually by the seller; no courier dispatch API is integrated." "External System"
        cloudinary = softwareSystem "Cloudinary" "Managed image storage for menu images, payment proof screenshots, and payment QR images." "External System"
        mailProvider = softwareSystem "Transactional Email" "Brevo SMTP in production, or Laravel log mail locally." "External System"
        fcm = softwareSystem "Firebase Cloud Messaging" "Optional best-effort Android order status push delivery." "External System"

        prepflow = softwareSystem "PrepFlow" "Pre-order, payment verification, fulfillment tracking, and kitchen-prep automation system." {
            web = container "Responsive Web Application" "Customer storefront and role-routed admin dashboard served as a static SPA." "Vite, React 18, TypeScript, Tailwind" {
                router = component "Route Shell" "Separates customer routes from role-protected admin routes." "React Router"
                authProvider = component "Auth Provider" "Bootstraps the session, stores current user state, and handles login/logout/profile flows." "React Context"
                apiClient = component "API Client" "Centralizes credentials, CSRF token retrieval, JSON parsing, and network error handling." "fetch wrapper"
                queryHooks = component "Feature Data Hooks" "Menu, order, config, prep, analytics, and admin mutation hooks." "TanStack Query"
                customerRoutes = component "Customer Workflows" "Menu, cart, checkout, payment proof upload, order tracker, and profile routes." "React routes"
                adminRoutes = component "Admin Workflows" "Dashboard, order queue, payment verification, prep, menu manager, and settings routes." "React routes"
                cartStore = component "Cart Store" "Local cart state keyed by menu item and quantity." "Zustand persist"
                sharedSchemas = component "Shared DTO Schemas" "Client-side validation mirror for API request shapes." "zod"
            }
            mobile = container "Android Mobile Application" "Capacitor wrapper around the React build with camera capture, local notifications, and FCM token registration." "Capacitor 6, Android"
            api = container "Backend API" "Session-authenticated JSON API for orders, menu CRUD, payment verification, prep, settings, email, and notifications." "PHP 8.2, Laravel 12, Docker" {
                routes = component "API Route Table" "Separates public, authenticated customer, and role:admin endpoint groups." "Laravel routes/api.php"
                guards = component "Request Guards" "Applies session auth, CSRF, throttling, and admin role enforcement." "Laravel middleware"
                authController = component "Auth Controller" "Register, login, logout, profile, password update, and password reset." "Laravel controller"
                menuController = component "Menu Controller" "Menu CRUD, Cloudinary image upload, and recipe ingredient mapping." "Laravel controller + PDO"
                orderController = component "Order Controller" "Batch validation, order creation, payment proof upload, lifecycle transition, audit log, email, and push triggers." "Laravel controller + transactions"
                configController = component "Config Controller" "Batches, shipping zones, payment methods, and fulfillment options." "Laravel controller"
                prepController = component "Prep Controller" "Dish totals, procurement aggregation, inventory, and purchase history." "Laravel controller + PDO"
                notificationController = component "Notification Token Controller" "Registers and removes native FCM tokens." "Laravel controller"
                jsonContract = component "JSON Response Contract" "Explicit Content-Type and json_encode response envelope." "JsonResponds trait"
                imageValidator = component "Image Input Validator" "Validates JSON data URL image uploads before Cloudinary calls." "DataUrlImage support class"
                receiptOcr = component "Receipt OCR Service" "Extracts advisory receipt text and parsed hints; never auto-approves payment." "Cloudinary OCR / Tesseract"
                pushService = component "Order Push Service" "Sends best-effort customer status notifications when Firebase is configured." "FCM HTTP v1"
                mailables = component "Mailables" "Password reset, order confirmation, and courier-link emails." "Laravel Mail"
                persistence = component "Persistence Boundary" "Prepared statements, Eloquent models, DB transactions, row locks, migrations, and relationships." "PDO, Eloquent, DB::transaction" "Database"
            }
            database = container "Operational Database" "Business records, sessions, cache, password reset tokens, FCM tokens, and audit logs." "TiDB Cloud / MySQL-compatible" "Database"
        }

        customer -> web "Uses" "HTTPS"
        admin -> web "Uses protected admin routes" "HTTPS"
        customer -> mobile "Uses installed app" "Android"
        customer -> paymentApps "Transfers payment outside PrepFlow" "Mobile wallet / bank app" "Manual"
        admin -> couriers "Books courier outside PrepFlow" "Courier app / manual booking" "Manual"

        web -> api "Calls through same-origin /api rewrite" "HTTPS, JSON, session cookie, CSRF"
        mobile -> api "Calls directly" "HTTPS, JSON, credentials"
        mobile -> web "Wraps the production React build" "Capacitor sync"
        api -> database "Reads and writes" "PDO prepared statements, Eloquent, MySQL SSL"
        api -> cloudinary "Uploads and reads image URLs" "HTTPS"
        api -> mailProvider "Sends order and password-reset email" "SMTP"
        api -> fcm "Sends order-status push when configured" "FCM HTTP v1"
        api -> couriers "Stores pasted courier note or tracking link" "Manual text / URL" "Manual"
        api -> paymentApps "Displays seller QR/account details only" "Read-only configuration" "Manual"

        routes -> guards "Passes every request through"
        guards -> authController "Routes auth and profile requests"
        guards -> menuController "Routes catalog requests"
        guards -> orderController "Routes order and payment-proof requests"
        guards -> configController "Routes operational settings requests"
        guards -> prepController "Routes prep and inventory requests"
        guards -> notificationController "Routes device-token requests"

        authController -> jsonContract "Returns JSON"
        menuController -> jsonContract "Returns JSON"
        orderController -> jsonContract "Returns JSON"
        configController -> jsonContract "Returns JSON"
        prepController -> jsonContract "Returns JSON"
        notificationController -> jsonContract "Returns JSON"

        authController -> persistence "Reads and writes users, sessions, and password reset tokens"
        menuController -> persistence "Reads and writes menu items and recipe ingredients"
        orderController -> persistence "Reads and writes orders, order items, batches, payment methods, shipping zones, and audit logs"
        configController -> persistence "Reads and writes batches, shipping zones, payment methods, and fulfillment options"
        prepController -> persistence "Aggregates prep data and writes inventory/purchase rows"
        notificationController -> persistence "Stores and deletes native device tokens"
        persistence -> database "Reads and writes" "MySQL SSL"

        menuController -> imageValidator "Validates image data URLs"
        orderController -> imageValidator "Validates receipt data URLs"
        menuController -> cloudinary "Uploads menu and payment QR images" "HTTPS"
        orderController -> cloudinary "Uploads payment proof screenshots" "HTTPS"
        orderController -> receiptOcr "Requests receipt text hints"
        receiptOcr -> cloudinary "Reads uploaded proof image" "HTTPS"
        orderController -> pushService "Requests status push"
        pushService -> fcm "Sends push notification" "HTTPS"
        orderController -> mailables "Sends confirmation and courier-link email"
        authController -> mailables "Sends password reset email"
        mailables -> mailProvider "Sends email" "SMTP"

        web -> routes "Sends JSON requests" "HTTPS"
        mobile -> routes "Sends JSON requests" "HTTPS"

        router -> customerRoutes "Routes public and customer pages"
        router -> adminRoutes "Routes admin pages after role check"
        authProvider -> apiClient "Verifies session and sends auth mutations" "JSON"
        customerRoutes -> queryHooks "Reads and mutates customer data"
        adminRoutes -> queryHooks "Reads and mutates admin data"
        customerRoutes -> cartStore "Adds, updates, and clears cart lines"
        queryHooks -> sharedSchemas "Validates mutation payloads"
        queryHooks -> apiClient "Calls the API wrapper"
        apiClient -> routes "Sends JSON requests" "HTTPS"

        production = deploymentEnvironment "Production" {
            deploymentNode "Customer / Admin Device" "Browser-capable device" "User device" {
                deploymentNode "Web Browser" "Chrome, Firefox, Edge, Safari" "Browser" {
                    containerInstance web
                }
            }

            deploymentNode "Customer Android Device" "Android device" "Android" {
                containerInstance mobile
            }

            deploymentNode "Public Edge" "DNS, TLS, CDN, and WAF target" "Provider edge" {
                cdn = infrastructureNode "Static Web Hosting" "Vercel now; equivalent CDN hosting target. Serves SPA assets and rewrites /api/* to the API origin." "Vercel / CDN"
            }

            deploymentNode "Application Runtime" "Render Docker service now; horizontally scalable Docker target." "Docker runtime" {
                deploymentNode "prepflow-api A" "Primary API instance." "Docker, PHP 8.2, Laravel 12, Tesseract" {
                    containerInstance api {
                        healthCheck "API health" "https://prepflow-api.onrender.com/api/menu" 60 5000
                    }
                }

                deploymentNode "prepflow-api B" "Scale-out target using the same image." "Docker, PHP 8.2, Laravel 12, Tesseract" {
                    containerInstance api
                }
            }

            deploymentNode "Managed Data Plane" "Restricted managed SQL boundary." "TiDB Cloud / MySQL-compatible" {
                deploymentNode "Operational SQL Service" "Managed SQL database." "TiDB Cloud Starter / MySQL-compatible" {
                    containerInstance database
                }
                backups = infrastructureNode "Backup / Restore Control" "Managed database backup and restore target." "Managed backup"
            }

            deploymentNode "Provider Services" "Managed external services." "SaaS" {
                softwareSystemInstance cloudinary
                softwareSystemInstance mailProvider
                softwareSystemInstance fcm
            }

            deploymentNode "Operations Controls" "Delivery and runtime operations." "CI/CD and observability" {
                ci = infrastructureNode "CI/CD Pipeline" "Builds, tests, and deploys web and API artifacts." "GitHub / Vercel / Render"
                logs = infrastructureNode "Central Logs and Metrics" "API logs, deploy health, smoke checks, and error investigation." "Provider logs / probes"
                secrets = infrastructureNode "Secrets Boundary" "Provider environment variables or secret manager target." "APP_KEY, DB, Cloudinary, SMTP, FCM"
            }

            cdn -> web "Delivers static assets" "HTTPS"
            cdn -> api "Proxies /api requests" "HTTPS, JSON"
            database -> backups "Backs up to" "managed backup"
            ci -> cdn "Deploys static build"
            ci -> api "Deploys Docker image"
            api -> logs "Emits logs and health signals"
            secrets -> api "Injects runtime secrets"
        }
    }

    views {
        systemContext prepflow "system-context" {
            include customer admin prepflow paymentApps couriers cloudinary mailProvider fcm
            autoLayout lr 350 250
            title "PrepFlow - System Context"
        }

        container prepflow "container-view" {
            include customer admin web mobile api database cloudinary mailProvider fcm paymentApps couriers
            autoLayout lr 350 220
            title "PrepFlow - Container View"
        }

        component api "api-components" {
            include web mobile routes guards authController menuController orderController configController prepController notificationController jsonContract imageValidator receiptOcr pushService mailables persistence database cloudinary mailProvider fcm
            autoLayout lr 300 170
            title "PrepFlow - Backend API Components"
        }

        component web "client-components" {
            include router authProvider apiClient queryHooks customerRoutes adminRoutes cartStore sharedSchemas routes api
            autoLayout lr 300 170
            title "PrepFlow - Client Components"
        }

        dynamic api "receipt-verification-flow" {
            customer -> mobile "Uploads receipt screenshot"
            mobile -> routes "POST /api/orders/{id}/payment-proof"
            routes -> guards "Applies auth, CSRF, and ownership checks"
            guards -> orderController "Routes payment-proof request"
            orderController -> imageValidator "Validates data URL"
            orderController -> cloudinary "Uploads proof image"
            orderController -> receiptOcr "Extracts OCR hints"
            receiptOcr -> cloudinary "Reads uploaded proof image"
            orderController -> persistence "Stores proof URL, OCR data, payment_uploaded status, audit logs"
            orderController -> pushService "Attempts receipt-submitted push"
            admin -> web "Opens payment verification queue"
            web -> routes "GET /api/admin/orders?status=payment_uploaded"
            admin -> web "Verifies payment"
            web -> routes "PATCH /api/admin/orders/{id}/status"
            orderController -> persistence "Stores confirmed status and audit log"
            orderController -> mailables "Sends confirmation email"
            prepController -> persistence "Aggregates recipe ingredients for confirmed orders"
            autoLayout lr 300 170
            title "PrepFlow - Receipt Verification to Prep Flow"
        }

        deployment prepflow production "production-deployment" {
            include *
            autoLayout lr 350 220
            title "PrepFlow - Production Deployment"
        }

        styles {
            element "Person" {
                shape Person
                background #08427b
                color #ffffff
            }
            element "Software System" {
                background #1168bd
                color #ffffff
            }
            element "External System" {
                background #999999
                color #ffffff
            }
            element "Container" {
                background #438dd5
                color #ffffff
            }
            element "Component" {
                shape Component
                background #85bbf0
                color #000000
            }
            element "Database" {
                shape Cylinder
                background #2f855a
                color #ffffff
            }
            element "Infrastructure Node" {
                background #fef3c7
                color #111827
            }
            element "Deployment Node" {
                background #f8fafc
                color #111827
                stroke #94a3b8
                border dashed
            }
            relationship "Relationship" {
                routing Orthogonal
                color #4a4a4a
                thickness 2
            }
            relationship "Manual" {
                style Dashed
                color #a16207
                thickness 2
            }
        }
    }
}