Hub Backend: Building the REST API for a Pyrotechnics Equipment Management System

What Is Hub Backend?

hubbackend is the REST API that powers the Hub Frontend dashboard. It was built specifically for JAYS Pyrotechnics — a production company that manages high-value, safety-critical equipment across multiple events.

Before this system, equipment checkout was tracked on paper logs. The backend replaces that entirely with a strict, relational digital architecture where every asset movement is recorded, validated, and auditable.

Tech Stack

Layer	Technology
Framework	Laravel 11 (PHP)
Database	Supabase PostgreSQL
Authentication	Laravel Sanctum (stateless API tokens)
ORM	Eloquent (strictly — no raw SQL)
API Style	RESTful JSON

Core Architecture

Role-Based Access Control (RBAC)

Three distinct roles with strictly enforced permissions:

• admin — Full read/write access across all resources
• warehouse_manager — Full read/write access to operations
• site_manager — Read-only, scoped exclusively to their allocated events via the event_site_managers pivot table

The site manager scope is enforced at the query level — they cannot even see events they aren't assigned to, let alone modify them.

Asset Tracking

Every physical asset gets a unique asset_tag (e.g. JPLSF-M3/005). Key design decisions:

• Condition is boolean — true = Good, false = Damaged. No ambiguous middle states
• Timers are not standalone assets — Operational shot-timers attach to equipment rows via a has_timer flag
• No hard deletes — Retired assets have status set to retired, preserving all historical relationships and audit trails

The Two-Step Check-In Workflow

This is the most critical piece of business logic. Equipment check-in is a strict two-step process, and the API enforces this at the HTTP layer:

Step 1 — Receiving

• Marks items as physically received
• Records the timestamp (date_in)
• Assigns a return warehouse
• Updates item status to pending_inspection

Step 2 — Condition Assessment

• Cannot be performed unless Step 1 is complete — attempting it returns 422 Unprocessable Entity
• Records the item's physical condition
• If damaged → automatically logs a discrepancy to the asset_discrepancies table
• If good → updates status to in_stock

This two-step design mirrors real warehouse receiving workflows and prevents condition assessment from happening on items that haven't been physically verified as received.

API Design Principles

Strictly Eloquent — No raw SQL queries anywhere in the codebase. All database interactions go through Eloquent models and relationships. This ensures the ORM's query builder handles escaping and prevents SQL injection by default.

Stateless tokens via Sanctum — The API is consumed by the React SPA, so it uses Sanctum's stateless token mode rather than session-based auth. Tokens are issued on login and sent as Authorization: Bearer headers on every request.

422 over 400 — Where business logic validation fails (not input validation), the API returns 422 Unprocessable Entity with a structured error body. This distinction matters for the frontend to correctly differentiate between bad input and workflow violations.

Data Integrity for Safety-Critical Equipment

Pyrotechnics equipment management isn't just a logistics problem — it has safety implications. Key integrity decisions:

• Asset tags are immutable — Once assigned, an asset_tag cannot be changed
• Discrepancy logging is automatic — Damaged returns are logged without requiring a manual step from the warehouse manager
• Soft deletes everywhere — Nothing is ever truly removed; the audit trail is sacred

Laravel 11 Specifics

Laravel 11 introduced a slimmer application skeleton compared to L10. The bootstrap/app.php file now centralises middleware and exception handling configuration that previously lived in separate Http/Kernel.php and Exceptions/Handler.php files. This backend takes full advantage of the new structure for cleaner middleware registration.

View on GitHub →