Executive Summary

    WeMix ERP Executive Customer Delivery Report

    Date: 2026-05-07
    Prepared for: Customer Delivery and Go-Live Operations
    Repository: wemix-web-ui

    1) Executive Overview

    WeMix is delivered as an integrated concrete delivery ERP platform with:

    • customer ordering and tracking
    • role-based operations dashboards
    • dispatch, delivery execution, and truck telemetry lifecycle controls
    • finance, quality, weather, and communication operations modules
    • CRM and customer inquiry pipelines
    • API-level and workflow-level test coverage for core business logic

    The implementation now includes hardening for cross-object consistency (orders, deliveries, trucks, execution, billing, ratings), structured API error contracts, Stripe payment reconciliation, and automated integration tests using isolated in-memory MongoDB.

    2) System Architecture (High-Level)

    • Frontend/UI: pages/, src/components/
    • API layer: pages/api/**
    • Domain models: models/**
    • Business logic / invariants: lib/erpLinking.ts, lib/erpAccess.ts, lib/requestAuth.ts
    • Shared API error contract: lib/apiResponse.ts
    • External integrations: Stripe, Resend, Twilio WhatsApp, OpenAI support chat

    3) Feature-by-Feature Delivery Inventory

    Each module below includes:

    • business intent
    • user-visible behavior
    • primary code locations
    • validation/business rules
    • automated test coverage status

    3.1 Authentication and Access Control

    What it does

    • Supports password login, OTP, magic link, guest access, and role-aware authorization.
    • Protects privileged operations via JWT or scoped API keys.

    How it works

    • Token generation/verification: lib/auth.ts
    • Request auth context and role/scope checks: lib/requestAuth.ts
    • ERP role access control and franchise scoping: lib/erpAccess.ts
    • Auth endpoints: pages/api/auth/*

    Business rules

    • Unauthorized requests return 401, forbidden actions return 403.
    • Role and feature-flag checks gate login method availability.

    Test evidence

    • Integration auth flow test:
      • tests/integration/api/customer/auth-and-payments.test.ts
    • Unit auth-adjacent API and utility tests:
      • tests/unit/lib/api.test.ts, tests/unit/api/health.test.ts

    3.2 Customer Order Intake (Web and Mobile)

    What it does

    • Collects customer order details, validates serving area, and submits order request.
    • Supports pay-now and pay-later flows.

    How it works

    • Web order flow: pages/order.tsx
    • Mobile order flow: pages/order-mobile.tsx
    • Order request API: pages/api/order-requests/index.ts
    • Serving area validation: lib/activeServingArea.ts
    • Order ID and QR generation: lib/orderId.ts

    Business rules

    • Required contact, location, and build fields enforced.
    • Serving area ZIP validation blocks unsupported regions.
    • Unique order ID generation with collision checks.

    Test evidence

    • Unit tests:
      • tests/unit/activeServingArea.test.ts
      • tests/unit/lib/orderId.test.ts
      • tests/unit/api/calculate-concrete.test.ts

    3.3 Stripe Payment and Reconciliation

    What it does

    • Creates checkout session for deposit payments.
    • Reconciles successful checkout to OrderRequest and Billing via webhook.

    How it works

    • Session creation API: pages/api/stripe/create-checkout-session.ts
    • Webhook reconciliation API: pages/api/stripe/webhook.ts
    • Billing persistence model/API: models/Billing.ts, pages/api/billing/index.ts, pages/api/billing/[id].ts

    Business rules

    • Checkout now requires orderRequestId.
    • Session metadata includes order linkage.
    • Webhook reconciliation is idempotent by Stripe session reference.

    Test evidence

    • Integration tests:
      • tests/integration/api/customer/auth-and-payments.test.ts
      • tests/integration/api/core/workflow-linkage.test.ts

    3.4 Dispatch and Scheduling

    What it does

    • Assigns franchise, truck, and driver to order requests.
    • Creates and manages deliveries by schedule.

    How it works

    • Deliveries API: pages/api/deliveries/index.ts, pages/api/deliveries/[id].ts, pages/api/deliveries/by-order.ts
    • Scheduling APIs: pages/api/scheduling/slots.ts, pages/api/scheduling/recommend.ts, pages/api/scheduling/calendar.ts
    • Core linkage and validation logic: lib/erpLinking.ts

    Business rules

    • Delivery links validated across OrderRequest/Truck/Driver/Franchise.
    • Capacity, franchise ownership, and schedule conflict constraints enforced.
    • Delivery status transitions enforced via transition matrix.

    Test evidence

    • Unit scheduling slots:
      • tests/unit/api/scheduling-slots.test.ts
    • Integration lifecycle scenarios:
      • tests/integration/api/core/workflow-linkage.test.ts

    3.5 Delivery Execution Lifecycle

    What it does

    • Captures departure, arrival, pour timings, sign-off, and QA values.
    • Keeps OrderRequest and Truck operational state synchronized.

    How it works

    • Execution APIs: pages/api/delivery-executions/index.ts, pages/api/delivery-executions/[id].ts
    • Sync engine: lib/erpLinking.ts (syncDeliveryLinks, releaseDeliveryLinks)
    • Delivery model: models/Delivery.ts
    • Delivery execution model: models/DeliveryExecution.ts

    Business rules

    • One execution record per delivery.
    • Execution orderRequestId must match delivery linkage.
    • Execution milestones derive/advance delivery status.
    • Deleting execution re-reconciles delivery status.

    Test evidence

    • Integration:
      • tests/integration/api/core/workflow-linkage.test.ts

    3.6 Fleet and Truck Telemetry

    What it does

    • Manages fleet metadata, operational status, and telemetry updates.

    How it works

    • Truck APIs: pages/api/trucks/index.ts, pages/api/trucks/[id].ts
    • Truck model: models/Truck.ts
    • Dashboard fleet and tracking UX: pages/dashboard/[role].tsx

    Business rules

    • Driver role can only edit telemetry fields on assigned truck/delivery contexts.
    • Active delivery constraints block destructive truck actions.

    Test evidence

    • Integrated indirectly through workflow linkage tests:
      • tests/integration/api/core/workflow-linkage.test.ts

    3.7 Billing and Financial Records

    What it does

    • Manages invoice/payment records with franchise and order linkage.

    How it works

    • Billing APIs: pages/api/billing/index.ts, pages/api/billing/[id].ts
    • Billing model: models/Billing.ts

    Business rules

    • Franchise consistency checks for linked order and order request records.
    • Non-negative amount validation.

    Test evidence

    • Integration CRUD and validation:
      • tests/integration/api/core/workflow-linkage.test.ts

    3.8 Driver Ratings and Service Quality Feedback

    What it does

    • Captures customer ratings for completed deliveries.

    How it works

    • Ratings API: pages/api/driver-ratings/index.ts
    • Ratings model: models/DriverRating.ts

    Business rules

    • Delivery must exist, belong to rated driver, and be completed.
    • Linked order request must be completed.
    • Unique rating per driver-delivery pair.

    Test evidence

    • Integration:
      • tests/integration/api/core/workflow-linkage.test.ts

    3.9 Operations Modules (Inventory, Batch, Driver Performance)

    What it does

    • Supports production-side operations and KPI tracking.

    How it works

    • Plant inventory APIs: pages/api/plant-inventory/index.ts, pages/api/plant-inventory/[id].ts
    • Batch run APIs: pages/api/batch-runs/index.ts, pages/api/batch-runs/[id].ts
    • Driver performance APIs: pages/api/driver-performance/index.ts, pages/api/driver-performance/[id].ts
    • Models: models/PlantInventory.ts, models/BatchRun.ts, models/DriverPerformance.ts

    Business rules

    • Franchise-scoped write access and admin controls.
    • Required fields and domain numeric validation via model + API conversion.

    Test evidence

    • Integration CRUD suite:
      • tests/integration/api/operations/operations-crud.test.ts

    3.10 Quality, Alerts, and Weather Operations

    What it does

    • Manages complaints, operational alerts, and weather conditions affecting pours.

    How it works

    • Complaint APIs: pages/api/complaints/index.ts, pages/api/complaints/[id].ts
    • Alert APIs: pages/api/alerts/index.ts, pages/api/alerts/[id].ts
    • Weather APIs: pages/api/weather-conditions/index.ts, pages/api/weather-conditions/[id].ts
    • Models: models/Complaint.ts, models/Alert.ts, models/WeatherCondition.ts

    Business rules

    • Franchise/driver scope-aware retrieval and modification.
    • Acknowledgment metadata for alert lifecycle.
    • Admin-only weather controls.

    Test evidence

    • Integration CRUD suite:
      • tests/integration/api/quality/quality-crud.test.ts

    3.11 CRM and Customer Inbound Modules

    What it does

    • Captures contact requests, demo requests, leads, and franchise interest.

    How it works

    • Contacts API: pages/api/contacts/*
    • Demo requests API: pages/api/demo-requests/*
    • Leads API: pages/api/leads/*
    • Franchise API: pages/api/franchises/*

    Business rules

    • Public intake with protections and admin-side management.
    • Notification workflows via integrated messaging services.

    Test evidence

    • Partial via existing unit/E2E and system smoke coverage.

    3.12 Support Chat and Knowledge Assistance

    What it does

    • Provides AI-assisted support response generation.

    How it works

    • API: pages/api/support-chat.ts
    • Service: lib/supportChat.ts

    Business rules

    • Validates message array and role/content structure before processing.

    Test evidence

    • Integration validation test:
      • tests/integration/api/customer/auth-and-payments.test.ts

    3.13 Help and Documentation Experience

    What it does

    • In-app help center backed by markdown documentation.

    How it works

    • Help page renderer: pages/help.tsx
    • Help content source: docs/ERP-HELP-MANUAL.md
    • Operational testing and readiness docs: docs/TESTING.md, docs/production-readiness-audit.md

    4) Data Model Coverage (Core ERP Entities)

    Primary model files and business role:

    • models/OrderRequest.ts - customer order intake and schedule linkage
    • models/Delivery.ts - dispatch and operational delivery state
    • models/DeliveryExecution.ts - lifecycle event capture and customer sign-off
    • models/Truck.ts - fleet asset and telemetry state
    • models/User.ts - role-based identity and operational users
    • models/Franchise.ts - business unit and service area metadata
    • models/Billing.ts - financial records and payment linkage
    • models/DriverRating.ts - post-delivery customer quality signal
    • models/PlantInventory.ts, models/BatchRun.ts, models/DriverPerformance.ts - production and KPI operations
    • models/Complaint.ts, models/Alert.ts, models/WeatherCondition.ts - quality and risk operations

    5) Quality Assurance Summary

    Validation runs completed:

    • npm run test:run - passed
    • npm run test:integration - passed
    • npx tsc --noEmit - passed
    • npm run lint - passed with warnings, no errors

    Current totals observed:

    • 69 automated tests passed across unit + integration suites
    • Integration suite includes 16 tests across 4 ERP workflow domains

    6) Customer Delivery Readiness Statement

    The platform now includes:

    • deterministic cross-object ERP lifecycle handling
    • structured API reliability and error responses in hardened transactional routes
    • payment reconciliation wiring and idempotent billing linkage
    • automated integration validation of CRUD and workflow invariants for core ERP modules

    This report is intended as the customer handoff snapshot for delivered scope, implementation traceability, and operational verification evidence.