Building a Reusable Excel Mapping System

I built a Laravel and React workspace that lets users connect different Excel formats to one data model, validate configurations, and reuse approved mappings for future uploads.

My role: Designed and implemented the Laravel mapping workflow and React interface, including validation, versioning, permissions, edit locks, and background processing.

LaravelReactExcel mappingVersioned draftsWebSockets

The Challenge

Customer files used different column names, layouts, and value formats. Building a separate importer for every format slowed onboarding, required developer support, and made changes difficult to maintain.

The Solution

Preview and map the file

Users select the header row, review sample data, and connect each Excel column to the correct platform field through a visual workspace.

Validate and transform values

Required fields, data types, countries, dates, units, relationships, defaults, and duplicate mappings are checked before large datasets are processed.

Publish reusable versions

Mappings move through draft, published, archived, and historical states, allowing a new version to be prepared without changing the active configuration.

Handle changing file formats

A guided update compares new headers with the existing mapping, identifies added or removed columns, and keeps production uploads on the published version until approval.

Safe Collaboration

Tenant-level permissions isolate mappings between organizations. Edit locks prevent two users from changing the same draft, while published and historical versions remain protected from accidental updates.

Background Processing

Large-file analysis runs through Laravel queues. Private WebSocket events notify the React interface when processing finishes, providing immediate feedback without repeated polling.

Testing and Safeguards

Required fields, default values, data types, and transformations
Draft, published, archived, and historical versions
Mapping import, export, edit locks, and file-format updates
Company permissions and large Excel previews

Result

Supported different customer file structures through one workflow
Reduced the need for customer-specific import code
Made approved mappings reusable across future uploads
Found configuration problems before large datasets were processed
Allowed source formats to change without disrupting the active mapping

Key Takeaway

A reusable import system needs more than matching column names. Validation, version history, permissions, background processing, and a clear interface make the configuration safe for non-technical users.

Technologies

PHP, Laravel, React, TypeScript, Inertia.js, PostgreSQL, Laravel Queues, WebSockets, Amazon S3, Laravel Vapor, Pest, and PHPUnit.