System Overview & Workflows

A detailed guide to the core processes and business logic of our RFID system.

1. Establishing a New Batch

Everything in the system starts with a Batch. A batch represents a specific shipment or return from a customer.

Key Data Points:
  • Customer Name
  • Direction (IN/OUT)
  • Order Number
Process Steps:
Step A Navigate: Go to Operations > Portal Scan.
Step B Configure: Select the Customer and Direction.
Step C Initialize: Enter the Order Number and the first Cart Number.
Step D Launch: Click "Start Batch" to open the scanning session.

2. Sorting Tunnel Scanning

When items pass through the RFID portal, they are automatically detected and processed in real-time.

Automation: No manual scanning of individual tags is required. The portal reads hundreds of tags per second.
What happens when a scan occurs?
  1. Tag Detection: The RFID portal captures the EPC (Electronic Product Code) from each tag.
  2. Job Dispatch: The system sends tags to a background queue for rapid processing.
  3. Inventory Lookup: Each tag is matched against our Inventory database.
  4. Movement Logging: An InventoryTracking record is created, capturing the timestamp, location, and direction.
  5. Status Update: The item's current location and status are updated in the master inventory list.

3. Adding Tags to a Batch

New inventory can be registered during the scanning process or assigned to existing tags.

This ensures that even new items are immediately trackable within the current workflow.

Two Main Methods:
Enter New Inventory

Use this on the Portal Scan page to register items that haven't been seen by the system before. Specify the product type and expected count.

Manual Reprogrammer

Allows for bulk reassignment of existing tags to different product types (e.g., changing "Small Towel" to "Large Towel").

System Glossary & Key Terms
Inventory

The master list of every individual item (RFID tag) in the system. It tracks the current status and last known location.

Inventory Tracking

The movement ledger. Every scan creates a new entry here, providing a full audit trail of where items have been.

Cart

A container for scanned items. Used to organize work within a Batch. Multiple carts can belong to one Batch.

Direction (IN/OUT)

Determines if items are being returned by a customer (IN) or shipped out (OUT).

Location

A specific site or facility. Items are assigned to a location based on where they were last scanned.

Customer

The client associated with the shipment or return. Each customer typically has a default location.

Table of Contents
Controllers & Responsibilities
PortalScannerController

Runs the Portal Scan workflow: start batches, add/close carts, live scans (IN/OUT), hand scanner intake, manual/portal reprogrammer, and summary APIs.

  • Start Batch: Operations → Portal Scan
  • Scan Items: adds InventoryTracking rows and updates item status
  • Background dispatch: pushes tags to ProcessScannedTags
BatchController

Shows batch summaries with product/cart breakdowns; caches heavy summaries for performance.

  • Summary cache key: batch_summary_{batchId} (5 minutes)
InventoryController

Inventory index and dashboard metrics (aging, status/location distribution, IN/OUT trends).

  • Dashboard stats cache: inventory_dashboard_stats_v2 (60 minutes)
ScannerController

Scanner management and system health; statistics are pre-warmed on schedule.

  • Cache keys: scanners_index_stats_v3, scanner_show_stats_v3_{id}
UnitController

Unit (linen type) distribution and history reporting.

Customer/Order/Tag Controllers

CRUD and supporting operations for master data and tag management.

Caching vs Real-time

The system blends real-time processing with short‑lived caches to keep the UI fast while ensuring operational accuracy.

Real-time views
  • Portal Scan (batch/cart pages): scans are processed immediately via background jobs; counts update as jobs complete.
  • Manual/Portal Reprogrammer: changes take effect as soon as the job processes the tag list.
Cached views
  • Inventory Dashboard metrics: inventory_dashboard_stats_v2 for 60 minutes.
  • Batch summary: batch_summary_{batchId} for 5 minutes.
  • Scanner stats: warmed hourly via scanners:warm-cache.
Force-refresh
  • Dashboard: append ?refresh=1 to stats request (UI buttons may use this internally).
  • CLI: php artisan inventory:warm-cache
General cache clear
  • php artisan cache:clear
  • php artisan config:clear
Why we cache
  • Heavy aggregates (30‑day trends, large batch summaries)
  • Smoother UX during peak scan hours
Background Jobs & Queues
ProcessScannedTags
  • Deduplicates tag reads, bulk‑creates new Inventory items, updates existing ones.
  • Inserts InventoryTracking movements (IN/OUT) with timestamps, location, batch/cart context.
  • Queue: rfid-queue
Scheduled Tasks
  • inventory:match-cycles — every 4 hours. Links OUT→IN pairs and backfills unit_id.
  • report:cache-avg-timeout — every 4 hours. Warms average time‑out report cache.
  • scanners:warm-cache — hourly. Pre‑computes scanner stats.
  • inventory:warm-cache — hourly. Pre‑computes dashboard + index counts.
  • cleanup:test-scans — nightly cleanup of simulation/test data.
Running workers
  • Default connection: redis (e.g., database or redis)
  • Start worker: php artisan queue:work --queue=rfid-queue
Failed jobs
  • List failed: php artisan queue:failed
  • Retry: php artisan queue:retry all
Common User Tasks (How‑To)
Start a New Batch and Scan OUT to a Customer
  1. Go to Operations → Portal Scan.
  2. Select the Customer and choose Direction = OUT.
  3. Enter the Order Number and the first Cart Number.
  4. Click Start Batch and begin scanning items through the portal.
  5. Close the cart when full; optionally open the next cart.
Receive Returns (Scan IN)
  1. Start a new batch with Direction = IN for the returning customer.
  2. Run items through the portal; the system records IN movements.
Reprogram / Reassign Tags
  1. From Portal Scan, use Reprogram / Reassign Tags tools.
  2. Manual Reprogrammer: paste/scan tag list and select the new product.
  3. Portal Reprogrammer: live scan tags and assign a product.
Enter New Inventory
  1. On Operations → Portal Scan, use Enter New Inventory.
  2. Select the Product and expected quantity; scan with hand scanner or portal.
Reports & Analytics
  • Lost Inventory: identifies items not seen in 90+ days.
  • Aging Units: distribution by last seen window (0–30, 30–60, 60–90, 90+).
  • Average Time Out: cycle‑time for items between OUT and IN scans (cache warmed on schedule).
Troubleshooting
No new scans appearing
  • Ensure queue worker is running: php artisan queue:work --queue=rfid-queue
  • Check System Health page for scanner connectivity.
Metrics look stale
  • Use dashboard refresh or run php artisan inventory:warm-cache
  • Clear caches: php artisan cache:clear
Data Model Basics
Inventory

One row per tag; tracks current status/location and last seen.

InventoryTracking

Append‑only movement ledger of scans (IN/OUT) with timestamps and context.

Batch & Cart

Operational grouping for scanning sessions and physical containers.

Product & Unit

Catalog and grouping of linen types and SKUs.

Customer & Location

Clients and facilities used to scope batches and movements.

Cycle Matching

Scheduled task links OUT→IN pairs and backfills missing unit associations.

For additional support, please contact the system administrator.