Solid Waste Laravel 12 Migration Overview and Plan

Scope

This plan is based on a local code audit of:

• solidwaste_boost as the Laravel 12 target application
• solidwaste_42 as the active Laravel 4.2 legacy application

It does not yet include a live production database audit, production file storage audit, traffic analysis, or deployment automation review. Those need to happen before a production cutover.

Executive Summary

Do not treat this as an in-place Laravel framework upgrade.

solidwaste_42 should be treated as a legacy source system that gets replaced module by module inside solidwaste_boost, which should become the new system of record on Laravel 12. A direct upgrade path from Laravel 4.2 through intermediate framework versions would be higher risk, slower to validate, and harder to keep aligned with the current active-development state of the application.

The recommended strategy is:

1. Harden solidwaste_boost as the new application shell.
2. Audit and normalize the legacy schema and business rules.
3. Rebuild the legacy modules in bounded-context waves.
4. Run both systems in parallel while validating data and workflow parity.
5. Cut over only after repeatable imports, acceptance testing, and rollback planning are in place.

Current-State Audit

solidwaste_boost

• Laravel 12.53.0
• Livewire 4.2
• Tailwind CSS 4
• Clean starter structure with Vite
• Auth was not enabled initially; it now has a lightweight Livewire auth baseline with:
  • login
  • register
  • dashboard
  • logout
• Alpine is available through Livewire’s bundled frontend runtime via @livewireScripts, so a separate Alpine package is not required for this baseline
• Auth baseline verified with passing tests and a production Vite build

solidwaste_42

• Laravel 4.2.*
• Monolithic application created in 2015 and still under active development
• Route file is large and centralized:
  • app/routes.php is about 395 lines
  • about 200 route or route-group declarations
• Backend surface area is significant:
  • 30 controllers
  • 35 models
  • 114 view files
  • only scaffold-level automated tests are present
• Frontend stack is legacy and mixed:
  • Bower-managed dependencies
  • Bootstrap 3
  • jQuery and jQuery UI
  • Select2
  • x-editable
  • Vue 1.x
  • Vue is embedded directly inside Blade partials and templates
  • 165 Vue markers were found across views
• Data layer shows drift between code and operational reality:
  • only 8 migrations
  • only 4 seed-related files
  • 20 SQL dump files totaling about 31 MB
• Auth and authorization are custom:
  • route filters in app/filters.php
  • username-based login
  • account activation and lockout logic
  • authorization based on group-string checks like admin, powerUser, readOnly
• Configuration and security debt is present:
  • hardcoded database credentials in config
  • hardcoded SMTP credentials in controller code
• Asset/deployment assumptions are not fully self-contained in the repo:
  • views reference /components, /js/app.js, and /css/styles.css
  • those public assets are not present in the repository snapshot that was audited

Primary Legacy Domains

These are the highest-surface modules by route/controller usage and should drive migration sequencing:

Area	Evidence from audit	Migration impact
Accounts and auth	AccountController plus custom filters	High risk because behavior must be redesigned, not copied
Container logs	ContainerLogController has one of the largest route surfaces	Likely core operational workflow
Enforcement	EnforcementController has one of the largest route surfaces	Core compliance workflow with citations, photos, documents
Inspection	Large route and Vue footprint	Closely tied to enforcement and citations
Penalty actions	Significant controller and view surface	Requires business-rule validation
Haulers	Shared dependency for multiple modules	Likely central reference entity
Transfer station / damaged container / vehicle / waste facility / DART	Multiple specialized controllers	Better migrated after core entities stabilize
Time and attendance / sign in-out	Separate workflow and signatures	Needs dedicated UX and data review
Documents / photos / email	Cross-cutting infrastructure	Must be planned before cutover
Reports / exports	PDF, Excel, and report views	Often a late-stage blocker if not audited early

Recommended Target Architecture

Use solidwaste_boost as the target system with:

• Laravel 12 for the application framework
• Livewire 4 for full-page and embedded interactive workflows
• Alpine for lightweight client-side behavior only
• Tailwind CSS 4 for all new UI styling
• Route middleware, policies, and gates for authorization
• Explicit service classes for complex workflow logic
• Repeatable import scripts for data migration
• Characterization tests and acceptance tests for parity validation

Recommended rule: avoid introducing Vue into the new application unless there is a proven need that Livewire and Alpine cannot satisfy.

Migration Strategy

Strategy choice

Use a greenfield replacement approach inside solidwaste_boost, not a version-by-version framework upgrade of solidwaste_42.

Why

• Laravel 4.2 to Laravel 12 is too large a framework gap for a safe direct code port
• the legacy app mixes framework logic, business rules, UI behavior, and old frontend libraries in the same templates
• custom auth and custom file/email behavior need redesign anyway
• the application is still changing, which makes long-lived in-place upgrade branches fragile

Phased Execution Plan

Phase 0: Freeze the migration rules

• Decide that solidwaste_boost is the target application
• Define how active changes in solidwaste_42 will be tracked during migration
• Create a module backlog and ownership list
• Capture a full production database dump and file-storage inventory
• Document current environments, cron jobs, queues, email flows, and report/export jobs

Exit criteria:

• target repo and migration governance are agreed
• production assets and databases are inventoried
• there is a process for syncing ongoing legacy changes into the migration backlog

Phase 1: Harden the Laravel 12 foundation

• Keep solidwaste_boost as a clean application shell
• Decide the permanent auth stack
• Define authorization design for legacy groups such as admin, powerUser, and readOnly
• Add core app layout, navigation, dashboard, error handling, and base testing patterns
• Set environment-based config for mail, database, files, queues, and app secrets
• Add CI checks for tests, formatting, and builds

Exit criteria:

• new app boots cleanly in local and staging environments
• auth and authorization direction is approved
• secrets are environment-driven only

Phase 2: Data and schema reconciliation

• Reverse-engineer the real production schema from the live database, not only from legacy migrations
• Compare live schema against:
  • legacy models
  • SQL dump files
  • existing migrations
  • current reports and exports
• Identify canonical tables, obsolete tables, and denormalized columns
• Define new Laravel 12 migrations for the target schema
• Design import scripts that can be run repeatedly in staging
• Decide which legacy IDs must be preserved and where mapping tables are needed

Exit criteria:

• target schema is approved
• import scripts are repeatable
• at least one full staging import succeeds

Phase 3: Auth, users, permissions, and shared reference data

• Rebuild users, login, password reset, activation policy, and lockout policy in Laravel 12
• Replace string-based group checks with middleware, policies, and explicit roles/permissions
• Migrate dropdowns, citations, inspectors, categories, towns, and other shared reference tables
• Migrate account photos and profile-related data if still required

Exit criteria:

• user access and shared lookup data work in the new app
• authorization rules are test-covered
• legacy and new access rules are mapped and signed off

Phase 4: Core operational modules

Recommended order:

1. Haulers
2. Container logs
3. Inspections
4. Enforcement
5. Penalty actions

For each module:

• Map routes, controllers, models, views, reports, and exports
• Write workflow acceptance criteria with real users
• Rebuild screens in Livewire and Tailwind
• Replace Vue 1 widgets with Livewire state and Alpine interactions
• Port validation and business rules into requests, actions, or service classes
• Migrate data and verify row-level parity
• Add feature tests and regression coverage

Exit criteria:

• each module has signed-off workflow parity
• imported data matches expected counts and sample records
• critical flows are test-covered

Phase 5: Peripheral modules and cross-cutting systems

• Transfer station
• Damaged container
• Vehicle, vehicle incidents, inspections, and repairs
• Waste facility reports
• DART operational reports
• Time and attendance / sign in-out
• Documents, images, sharing, email, and rotation workflows
• Reporting, PDF generation, and Excel exports

Exit criteria:

• all required modules are rebuilt
• file and report outputs are validated against legacy expectations

Phase 6: Parallel run and cutover readiness

• Stand up staging with production-like infrastructure
• Run full imports repeatedly from current production data
• Perform UAT with operational users
• Run legacy and new workflows in parallel where feasible
• Compare reports, exports, and critical counts between systems
• Prepare rollback and re-run procedures

Exit criteria:

• business owners approve parity
• cutover runbook is complete
• rollback path is documented and tested

Phase 7: Production migration

• Freeze legacy writes during cutover window
• Run final data import
• Validate counts, attachments, and user access
• Switch traffic to Laravel 12
• Closely monitor logs, queues, mail, and user-reported issues
• Keep legacy system available in read-only mode for a defined period

Exit criteria:

• new system is stable in production
• legacy system is no longer needed for operational writes

Non-Negotiable Technical Workstreams

These workstreams should run alongside the phases above:

• Security cleanup
• Configuration cleanup and secret rotation
• Testing and characterization coverage
• Data migration tooling
• File/image storage migration
• Reporting and export validation
• Logging, monitoring, and audit trails
• Performance testing for large lists, filters, and reports

High-Risk Items That Need Early Decisions

• Whether current legacy group strings should become a simple role enum or a full permission model
• Whether legacy file storage paths are still on local disk, shared storage, or another external location
• Which reports are operationally critical and must match exactly on day one
• Which modules are still heavily used versus effectively dormant
• Whether some features should be retired instead of migrated
• How ongoing legacy changes will be triaged during the migration period

Production Readiness Checklist

• Full production database audit completed
• Full production file audit completed
• Secrets removed from source and rotated
• Staging environment mirrors production architecture
• Repeatable import scripts verified
• UAT sign-off collected by module
• Monitoring and alerting enabled
• Rollback plan tested
• Read-only legacy fallback defined

Open Questions

• What does the actual production schema look like today?
• Where are uploaded files, photos, and generated documents stored?
• Which reports or exports are legally or operationally sensitive?
• Are there scheduled jobs, background tasks, or email workflows not visible in the repo?
• Are all legacy modules still active, or can some be retired?
• Is there a preferred role/permission package, or should authorization stay framework-native?

Recommended Next Steps

1. Review and edit this document for business priority and module order.
2. Audit the live production database and storage layout.
3. Decide the final authorization model for the Laravel 12 application.
4. Build the Phase 2 schema map before any large-scale module coding starts.
5. Start the first migration wave with shared reference data, auth, haulers, and container logs.