PIT Backend: Laravel API for Equipment Repair & Tracking

What Is PIT Backend?

pitbackend is the REST API for the PIT Equipment Repair & Tracking System — a full-stack application that replaces paper-based repair logs with a strict, relational digital workflow. It serves the pitfrontend React dashboard.

The system manages the complete repair lifecycle for production equipment: intake, fault logging, diagnosis, spare parts tracking, and resolution — across four user roles with tightly scoped access.

Tech Stack

Layer	Technology
Framework	Laravel 11+ (PHP)
Authentication	Laravel Sanctum (stateless token-based)
ORM	Eloquent (no raw SQL dialects)
Dev/Test Database	Supabase PostgreSQL
Production Database	Native MySQL (cPanel shared hosting)
Hosting	cPanel shared environment
Testing	PHPUnit (phpunit.xml)

Server Architecture

The Laravel core is stored above the public_html root for security — only the public entry point and compiled frontend assets are web-accessible:

cPanel Server
├── (above public_html)  ← Laravel framework core (secured)
│   ├── app/
│   ├── database/
│   └── routes/
└── public_html/         ← Web-accessible root only
    ├── index.php        ← Symlinked Laravel public entry
    └── /dist            ← Compiled React static assets

A custom .htaccess (present at the repo root) handles routing from the public entry point into the secured framework core.

Role-Based Access Control

The system uses a dual-layer guard: Laravel CheckRole middleware on the backend + React ProtectedRoute on the frontend.

Role	Scope
admin	Full system control, user creation, configuration
electronics_head	Equipment registration, ticket intake
technician	Diagnostics, status updates — assigned tickets only
management	Read-only analytics and data exports

Every API route except POST /api/login requires a valid Sanctum token. Unauthorized role access returns 403 Forbidden.

Database Schema

Equipment — Alphanumeric Primary Keys

Auto-incrementing integer PKs are explicitly forbidden on the equipment table.

Equipment IDs are assigned at physical intake as alphanumeric strings (e.g. LED-P3.9-001). This mirrors the physical labelling system in the warehouse and makes IDs human-readable in reports and QR codes.

equipment_id   VARCHAR (PK)    e.g. "LED-P3.9-001"
equipment_name VARCHAR         Required
category       ENUM            led | pyro | laser | audio | power
brand_model    VARCHAR         Required
serial_number  VARCHAR         Unique per manufacturer

Repair Tickets

ticket_id       BIGINT (PK)     Auto-increment
equipment_id    VARCHAR (FK)    → equipment
reported_by     BIGINT (FK)     → users
assigned_to     BIGINT (FK)     → users (technician)
status          ENUM            open | diagnosed | in_repair | pending_parts | resolved
fault_desc      TEXT            Required

Spare Parts

part_id         BIGINT (PK)
part_name       VARCHAR         Required
part_number     VARCHAR         Unique
quantity_stock  INT             Current available stock

5-Stage Repair Workflow

The ticket lifecycle enforces sequential stage transitions — a ticket cannot skip stages:

open → diagnosed → in_repair → pending_parts → resolved

1. Open — Electronics head raises ticket on intake
2. Diagnosed — Technician logs fault diagnosis
3. In Repair — Active repair work underway
4. Pending Parts — Repair blocked awaiting spare parts
5. Resolved — Repair complete, equipment returned

The API returns 422 if a stage transition is attempted out of order.

Documentation

The repo is notably well-documented with dedicated markdown files:

• README.md — Full system overview, schema, RBAC rules
• apiconfig.md — API endpoint reference
• config.md — Configuration and environment setup
• designer.md — UI design specifications for the frontend
• rules.md — Engineering constraints and business rules
• skills.md — Detailed implementation guide (23KB)
• spare_parts_diagrams.md — Parts relationship diagrams

View on GitHub →