Waste Vantage Legacy — Technical Documentation Index
Auto-generated blueprint. Reverse-engineered from the project workspace on 2026-05-11. This is the canonical entry point for all technical documentation.
1. Project Overview
Waste Vantage Legacy is an enterprise-grade waste management platform that orchestrates the full operational lifecycle of a waste collection business — from online order booking and runsheet scheduling, through driver dispatch and task management, to automated invoicing, Xero accounting sync, and Stripe payment collection.
Architecture Note: The system uses a Single-Tenant (Dedicated Installation) architecture. A fresh, dedicated installation (with a separate database, codebase, and environment configurations) is deployed for each new company or client. It exposes distinct portals for Admin operators, Drivers (mobile API), and end Customers.
2. Tech Stack
Confirmed from composer.json and package.json:
| Layer | Technology | Version |
|---|---|---|
| Backend Framework | Laravel | 5.8.* |
| Runtime | PHP | ^7.1.3 (enforced: 7.4) |
| Frontend Framework | Vue.js | ^2.5.17 (Vue 2) |
| CSS / Layout | Bootstrap | ^4.1.0 |
| Build Tool | Laravel Mix (Webpack) | ^4.0.7 |
| State Management | Vuex | ^3.6.2 |
| HTTP Client | Axios | ^0.19 |
| Alerts / Confirmations | SweetAlert2 | ^10.16.7 |
| PDF Generation | barryvdh/laravel-dompdf | ^0.8.2 |
| Accounting Integration | Xero API | (via custom XeroServices) |
| Payment Gateway | Stripe | stripe/stripe-php ^7.67 |
| SMS Provider | Twilio | twilio/sdk ^6.36 |
| Permissions | spatie/laravel-permission | 3.0 |
| Activity Logging | spatie/laravel-activitylog | ^3.9 |
| Excel Export | maatwebsite/excel | ^3.1 |
| Real-time Events | Laravel Echo + Pusher | ^1.11.1 / ^7.0.3 |
| Auth (API) | Laravel Passport | ^7 |
3. Route Files
routes/
├── admin.php # All admin panel routes (largest file, ~116 KB)
├── dashboard.php # Supplier/vendor dashboard routes (~43 KB)
├── api.php # General API routes
├── api-app.php # Mobile App API v1
├── api-app2.php # Mobile App API v2
├── api-driver.php # Driver-specific API endpoints
├── api-client.php # Customer-facing API
├── api-public.php # Public/unauthenticated API
├── customer.php # Customer portal web routes
├── supplier.php # Supplier portal web routes
├── web.php # Main web entry routes
└── channels.php # Laravel Echo broadcast channels
4. Application Architecture
The backend follows a Controller → Repository → Service layered pattern.
app/
├── Http/Controllers/Admin/ # Admin portal controllers (grouped by module)
├── Repositories/ # Business logic & DB query layer (46 files)
├── Services/ # Third-party integrations
│ ├── XeroServices.php
│ ├── StripeServices.php
│ ├── SendSmsServices.php
│ ├── EwalletService.php
│ └── GooglePlacesService.php
├── Jobs/ # Queued background jobs
├── Events/ & Listeners/ # Laravel event system
├── Mail/ # Mailable classes
├── Notifications/ # Laravel notifications
└── Observers/ # Eloquent model observers
Vuex Store Modules (resources/js/store/):
| Store Module | Purpose |
|---|---|
NewSkipBinOrder.js | Skip bin order creation wizard state |
RentalBinsOrder.js | Rental bin order state |
Disposal.js | Disposal order state |
NewOrder.js | Generic new order state |
WorkflowAction.js | Automation workflow builder state |
Message.js | Driver chat messaging state |
5. Core Business Modules
5.1 Order Management
Controllers: OrderController.php (255 KB), OrderSkipBinController.php, OrderLiquidController.php, OrderFunnelController.php, OrderCancelController.php, OrderPendingController.php, OrderQuoteController.php
Repositories: OrderRepository.php, OrderRentalRepository.php, Orderv2Repository.php, OrderFunnel.php
Vue Components: NewSkipBinOrder.vue, AdminNewSkipBinOrder.vue, AdminEditOrder.vue, EditOrder.vue, CreatePickup.vue, ChangeOver.vue
The central module of the system. Manages the full lifecycle of a waste collection job: order creation (via admin, supplier portal, or customer-facing web form/API), type classification (Skip Bin, Rear Lift, Wheel Bin, Front Bin, Rental, Liquid, Disposal), status transitions, pricing calculation, discount/coupon application, and handoff to the task/runsheet layer.
Key sub-features:
- Order Draft saving
- Order Funnel (public-facing booking flow with supplier routing)
- Change-Over orders (bin swap on-site)
- Cancellation with configurable fee types (
nominalorpercentage) - On-Hold flag for orders awaiting approval
5.2 Task & Runsheet Management
Controllers: TaskController.php (38 KB), TaskRunsheetController.php (84 KB), RunsheetGroupController.php (38 KB), RunsheetRentalController.php, RunsheetSessionController.php, ScheduleController.php
Repositories: TaskRepository.php (85 KB), TaskExtraServiceRepository.php, RunsheetGroupRepository.php, RunsheetRentalRepository.php, ScheduleGroupRepository.php
Vue Components: tasks/, runsheets/, runsheet-groups/, runsheet-sessions/
Manages the creation and sequencing of driver tasks from confirmed orders. Runsheets are grouped by driver and date. Rental bins use a separate recurring runsheet model (RunsheetRental) with automated schedule groups (ScheduleGroupJob) that regenerate tasks on a cycle. Supports drag-and-drop task reordering, route optimisation, and GPS-based live tracking.
5.3 Bin Hire & Container Management
Controllers: RentalBins/RentalBinsController.php (97 KB), GeneralWasteBinHireController.php (51 KB), RearLifts/RearLiftController.php, WheelBins/WheelBinController.php, FrontBins/FrontBinController.php
Repositories: RentalBin.php, OrderRentalRepository.php
Vue Components: rental-bins/, rear-lifts/, wheel-bins/, front-bins/
Handles the four primary bin-hire order types. Each type has its own controller, order lifecycle, and pricing model. The Rental Bins module supports long-term contracts with a Fuel Adjustment Factor (FAF) surcharge, bin placement tracking (BinLocation, BinPlacement), and weight capture at collection (BinWeight, BinDimension).
5.4 Invoicing & Accounting (Xero Integration)
Controllers: InvoiceController.php (Admin), Accounting/InvoiceController.php (93 KB), Accounting/PaymentController.php, Accounting/BillingController.php, Accounting/CreditController.php
Repositories: InvoiceManagement.php (198 KB — largest file), PaymentModule.php (78 KB), PaymentRepository.php
Services: XeroServices.php
Jobs: ProcessXeroInvoice.php, ProcessXeroPayment.php
Vue Components: invoices/, CreateInvoice.vue, HeaderInvoice.vue
Models: OrderInvoice, OrderInvoiceDetail, OrderInvoiceExtra, OrderPayment, OrderPaymentRefund, XeroTenant, XeroAccount, XeroItem, XeroWebhook, XeroInvoiceVoid
The financial core of the system. Generates invoices from completed tasks and orders, syncs them to Xero in real time, and applies payments (Stripe or manual). Critical rules enforced:
- All financial writes use
DB::beginTransaction(). - Invoice totals are immutable snapshots; FAF and overload charges are stored on
order_invoice_extras. - Xero sync is idempotent (webhook deduplication via
XeroWebhook). - Gross vs. Net Stripe fee separation is handled before syncing payments to Xero.
5.5 Payment Gateway (Stripe)
Controllers: PaymentVendor/ (sub-directory), Accounting/PaymentController.php
Services: StripeServices.php, Services/Stripes/ (sub-directory)
Models: StripeCheckout, StripeHook, OrderPayment
Vue Components: SkipBinStripe.vue, StripeBilling.vue, StripeSingleInvoice.vue, AdminSkipBinStripe.vue, LiquidStripe.vue, BillingPaymentStripe.vue
Manages Stripe Checkout sessions for customer-initiated payments and admin-initiated card charges. Handles webhook events to confirm payment status and trigger Xero payment sync. Supports payment expiration, refunds (OrderPaymentRefund), and fee-on-receipt configurations.
5.6 SMS Module (Twilio)
Controllers: SmsBalanceController.php, SmsBlashController.php
Repositories: SmsBalanceRepository.php, SmsBlashRepository.php, SmsTopUpRepository.php
Services: SendSmsServices.php
Jobs: SendSmsCampaign.php, SendSmsNotification.php, SendSmsInvoiceTopup.php, MonthlyTopUpJob.php
Models: SmsBalance, SmsCampaignHistory, SmsCampaignHistoryDetail, LogNotificationSmsBalance
Vue Components: sms-balances/, sms-blashs/, sms-blash-reportses/
Implements a two-pool credit system: monthly non-compounding credits (allocated per supplier package) and manual top-up credits. Credits are deducted when SMS is sent (task reminders, invoice notifications, bulk campaigns). Balance thresholds trigger low-balance warnings. See docs/modules/New_SMS_Monthly_Credit_Technical_Document.md for full design.
5.7 Driver & Fleet Management
Controllers: DriverController.php (27 KB), DriverLocationController.php, DriverTimesheetController.php, DriverChattingController.php
Repositories: DriverRepository.php, DriverTimesheet.php
Models: Driver, Vehicle, VehicleClass, DriverLocation, DriverLiveLocation, DriverWorking, DriverWorkingDay, Timesheet, ZoneDriver
Vue Components: DriverChatBar.vue, DriverListChat.vue, TrackMap.vue
Manages driver profiles, vehicle assignments, licence classes, working day schedules, GPS live tracking, and in-app chat. Supports Active/Inactive status with single-device session enforcement (admin can remotely revoke). Driver working days are configurable per zone.
5.8 Customer & Account Management
Controllers: CustomerController.php (36 KB, Admin), Accounting/CustomerController.php (113 KB), CustomerAddressController.php, CustomerNoteController.php, CustomerTypeController.php
Repositories: CustomerRepository.php (40 KB), BalanceRepository.php, EwalletManagement.php
Models: Customer, BusinessAccount, Address, BillingContact, CustomerNote, CustomerType, UserCreditLimit, CustomerEwallet, EwalletTransaction
Vue Components: customers/, ewallets/
Central CRM for end-customers. Each customer can belong to a BusinessAccount (organisation) and have multiple delivery addresses. Features include:
- Credit Limit gatekeeping: Running Balance = Xero unpaid + WIP orders.
- E-Wallet: Internal credit balance for order payments.
- Aged Receivables: Monthly snapshot system (
AgedReceivableSnapshot) for 30/60/90-day overdue tracking. - Opening Balance History: For statement reconciliation.
- Customer type segmentation (pre-paid, EOM, etc.).
5.9 Billing & Statements
Controllers: BillingController.php (Admin), Accounting/BillingController.php (25 KB), BillingCycleController.php, Accounting/StatementController.php
Repositories: StatementRepository.php, AgedReceivablesRepository.php (21 KB)
Models: BillingCycle, BillingCycleContract, BillingPayment, CustomerStatement, CustomerStatementInvoice, CustomerStatementBilling
Vue Components: AgedReceivables.vue
Manages periodic billing cycles for contracted customers. Generates consolidated statements and applies batch payments. The Aged Receivables dashboard (AgedReceivables.vue) reads from monthly aged_receivable_snapshots to display historical AR data without recalculating.
5.10 Pricing & Fuel Adjustment Factor (FAF)
Controllers: GeneralSettingController.php (33 KB)
Repositories: PricingRepository.php (107 KB — largest repository), FuelAdjustmentRepository.php, OrderContractRepository.php
Models: Pricing, PricingDate, PricingModule, PricingModuleItem, UnitPrice, OrderPricingModule, ScheduleUpdatePrice
Supports multiple pricing strategies per waste type, service area, and customer type (including VIP/Business accounts and daily pricing overrides). The FAF is a percentage surcharge stored as a static snapshot on order_details.faf_percent at the time of booking, ensuring historical invoices are never retroactively altered. See docs/adr/ADR-001-Fuel-Adjustment-Factor.md.
5.11 Supplier (Vendor/Tenant) Management
Controllers: VendorController.php (45 KB), UserRegisterController.php (64 KB), PartnerController.php
Repositories: ServiceAreaRepository.php, ServiceAreav2Repository.php
Models: Supplier, SupplierHasUser, SupplierPackage, SupplierServiceArea, Partner, SubCompany, ServiceArea, Zone, ZoneDetail
Each Supplier represents a tenant with its own branding (Partner), service area polygons, package entitlements (max runsheets, SMS credits, app features), and Xero/Stripe configuration. The Partner model holds all white-label configuration for the customer-facing booking widget.
5.12 Disposal & Transfer Station Management
Controllers: DisposalController.php, StationController.php, StationPriceController.php, OnGoingTranspackController.php
Repositories: DisposalRepository.php (25 KB)
Models: Disposal, DisposalExtra, DisposalTask, Station, StationType, StationPrice, StationPriceGroup
Tracks waste disposal events at transfer stations, linking them to specific tasks and orders. Captures weight, docket IDs, and bin weights. Station prices are configurable by group and waste type. Disposal extras support fixed and percentage price types.
5.13 Inventory Management
Controllers: InventoryManagementController.php
Repositories: InventoryManagement.php (10 KB), Inventoryv2Management.php
Models: InventoryItem, InventoryItemDetail, InventoryItemDate, InventoryStock, StockDate, Yard
Tracks physical bin and equipment inventory across multiple yards. Manages stock levels, item dates (delivery/collection scheduling), and links inventory items to specific order details and tasks.
5.14 Automation Workflow Engine
Controllers: Automation/WorkflowController.php
Models: AutomationWorkflow, AutomationWorkflowAction, AutomationWorkflowCondition, AutomationWorkflowTrigger, and associated master/list models.
Repositories (via Jobs): RerunRunsheetGroupsJob.php, ScheduleGroupJob.php
Vue Components: AutomationWorkflow.vue, WorkflowAction.vue, SupplierAutomationWorkflow.vue
A rule-based automation engine that triggers configurable actions (e.g., send SMS, create task, update status) based on defined conditions and event triggers (e.g., order created, task completed). Both admin and supplier-scoped workflows are supported.
5.15 Scrap Metal & Liquid Orders
Controllers: ScrapMetalController.php, OrderLiquidController.php (28 KB)
Models: ScrapMetalInquiry, Disposal (shared)
Vue Components: liquid-order/
Handles specialised order types for liquid waste collection and scrap metal inquiries, with their own pricing and task workflows. Scrap metal inquiries include supplier assignment and pricing negotiation flows.
5.16 Reporting & Analytics
Controllers: ReportController.php (34 KB), AgedReceivableSnapshotController.php, BillingPaymentReport.php, OrderPaymentReport.php, CommissionSummaryController.php, TransferReportController.php
Repositories: AgedReceivablesRepository.php, ReconciliationRepository.php
Vue Components: AgedReceivables.vue, dashboards/
Provides financial and operational reports: aged receivables (v4/v5 snapshots), billing payment reports, order payment summaries, commission tracking, and transfer/disposal reconciliation. Reports are generated from immutable snapshot tables where applicable to ensure historical accuracy.
5.17 Security, Users & RBAC
Controllers: UserController.php, StaffController.php, RoleController.php, SecurityMonitoringController.php
Repositories: UserRepository.php, AdminRepository.php
Models: User, Staff, Role, LoginHistory, UserDevice, UserSession, RequestLock
Packages: spatie/laravel-permission 3.0, spatie/laravel-activitylog ^3.9
Role-based access control with Spatie permissions. Login history is tracked per device. Single-device login enforcement for mobile (driver) accounts. A RequestLock model prevents concurrent duplicate submissions. Activity logging captures model changes for audit trails.
5.18 Notifications, Messaging & Email
Controllers: NotificationController.php, MessageController.php, EmailMarketingController.php
Jobs: SendSmsNotification.php, SendContractExpirationWarningJob.php, SendTaskReminderToCustomer.php
Models: Notification, Message, ChatRoom, MailSendLog, ReplayTemplate
Vue Components: DriverChatBar.vue, DriverListChat.vue
Multi-channel notification system: in-app notifications, driver chat (via Pusher), email (Laravel Mailer with MailSendLog for tracking), and SMS (via Twilio). Supports configurable notification templates per partner (task reminders, invoice delivery, contract warnings, on-route alerts).
5.19 Documents & Leads
Controllers: DocumentController.php, Document/ (sub-directory), LeadController.php, LeadsTypeController.php
Models: Document, DocumentCategory, DocumentTemplate, TermCondition, Lead, UserGuide
Vue Components: documents/
Manages uploadable documents (order attachments, T&C PDFs), document templates for automated generation, and a basic leads tracking module for pre-sales inquiries.
6. Background Jobs
| Job | Purpose |
|---|---|
ScheduleGroupJob | Regenerates rental runsheet tasks for a schedule group |
RerunRunsheetGroupsJob | Bulk-reruns all schedule groups (e.g., on FAF toggle) |
ProcessXeroInvoice | Syncs an invoice to Xero asynchronously |
ProcessXeroPayment | Syncs a payment to Xero asynchronously |
SendSmsCampaign | Dispatches bulk SMS campaign messages |
SendSmsNotification | Sends a single SMS notification |
MonthlyTopUpJob | Credits monthly SMS pool to all eligible suppliers |
SendSmsInvoiceTopup | Sends SMS top-up confirmation |
ExportCustomerJob | Generates customer export spreadsheet |
ExportFinancialReportJob | Generates financial report export |
SendContractExpirationWarningJob | Notifies customers of expiring rental contracts |
SendTaskReminderToCustomer | Sends day-before task reminder SMS/email |
7. Database Overview
The database schema has 816 migration files spanning 2014–2026, reflecting the system's evolution. Key table groupings:
| Domain | Core Tables |
|---|---|
| Orders | orders, order_details, order_drafts, order_categories |
| Invoicing | order_invoices, order_invoice_details, order_invoice_extras |
| Payments | order_payments, order_payment_invoices, order_payment_refunds |
| Tasks | tasks, task_details, task_status_histories |
| Runsheets | runsheet_groups, runsheet_rentals, runsheet_rental_tasks, runsheet_sessions |
| Customers | customers, business_accounts, addresses, billing_contacts |
| Financials | user_credit_limits, history_user_credits, aged_receivable_snapshots |
| Bins | bin_locations, bin_placements, bin_weights, bin_dimensions |
| Xero | xero_tenants, xero_accounts, xero_items, xero_tax_types, xero_webhooks, xero_invoice_voids |
| SMS | sms_balances, sms_campaign_histories, sms_campaign_history_details |
| Disposal | disposals, disposal_tasks, disposal_extras, stations, station_prices |
| Automation | automation_workflows, automation_workflow_actions, automation_workflow_triggers |
| Inventory | inventory_items, inventory_item_details, inventory_stocks, yards |
| Misc | public_holidays, priorities, zones, zone_details, zone_drivers |
8. Documentation Index
Architecture Decision Records (ADRs)
| File | Description |
|---|---|
| ADR-001: Fuel Adjustment Factor | Design decision for FAF snapshot approach on skip bin orders |
| ADR-002: FAF on Rental Orders | Extension of FAF to rental bin contracts and runsheet reruns |
| ADR-002: Pricing Category Support | Decision record for multi-category pricing model |
Module Technical Documents
| File | Description |
|---|---|
| SMS Monthly Credit System | Full technical spec for the two-pool SMS credit system |
| SMS Implementation Report | Implementation report and test outcomes for SMS credits |
| WasteType Multi-Category Endpoints | API endpoint reference for multi-category waste type support |
Daily / Working Documents
| File | Description |
|---|---|
| FAF Rental Implementation Plan | Step-by-step implementation plan for FAF on rental orders |
| TC-001: FAF Test Cases | Detailed test case specifications for FAF behaviour |
| FAF High-Level Test Plan | Summary test plan covering FAF acceptance criteria |
| Inactive Driver Changes Summary | Summary of backend/frontend changes for driver inactive logic |
| WasteType Migration Impact Report | Database and API impact analysis for multi-category migration |
| Aged Receivables Report v4 (HTML) | AR report design prototype v4 |
| Aged Receivables Report v5 (HTML) | AR report design prototype v5 |
Changelog
| File | Version |
|---|---|
| v2.0.0 | Initial v2 release notes |
| v2.1.6 | v2.1.6 changes |
| v2.1.11 | v2.1.11 changes |
| v2.1.12 | v2.1.12 changes |
| v2.13.33 | v2.13.33 changes |
| v2.13.52 | v2.13.52 changes |
| v2.13.59 | v2.13.59 changes |
| v2.15.70 | v2.15.70 changes |
| v2.17.74 | v2.17.74 changes |
Project Root Documents
| File | Description |
|---|---|
| readme.md | Laravel default readme |
| version.json | Current application version metadata |
| Access Waste.postman_collection.json | Postman API collection for testing endpoints |
9. Deployment & Server Notes
- PHP Binary: Always use the explicit PHP 7.4 binary for Artisan:
/usr/local/bin/ea-php74 artisan queue:work - CPanel Extensions Required:
fileinfo,GD(for Base64 image processing — signatures, task photos) - HTTPS Enforcement:
URL::forceScheme('https')is set inAppServiceProviderfor load-balanced environments. - PDF Assets: All Dompdf Blade views must use
public_path()for local assets (logos, images) — neverasset()orurl(). - Queue Driver: Background jobs (Xero sync, SMS dispatch, exports) run via the Laravel queue worker.
- Docker: A
Dockerfileis present in the project root for containerised deployments.