Files

2026-01-22 00:36:01 -06:00

8.3 KiB

Raw Blame History

ScanLook - Inventory Management System

Barcode-based inventory counting system designed for food production facilities

Replace 5 days of manual year-end physical inventory with a weekend project. Track variances, location errors, phantom lots, and ghost inventory in real-time.

🚀 Quick Start

1. Install Dependencies

pip install flask werkzeug --break-system-packages

2. Initialize Database

cd /home/claude/scanlook
python database/init_db.py

This creates the database with default users:

Owner: owner / owner123
Admin: admin / admin123
Staff: staff1 / staff123
Staff: staff2 / staff123

3. Run Application

python app.py

Access at: http://localhost:5000

📱 Accessing from Scanner Devices

For Zebra Android scanners or tablets on the same network:

Find your server's IP address:
```
hostname -I
```
On scanner device, open browser and navigate to:
```
http://YOUR_SERVER_IP:5000
```
Scanner trigger acts as Enter key (keyboard wedge mode)

👥 User Roles

Owner (Level 1)

Super admin privileges
Manage all admins
View all sessions across branches

Admin (Level 2)

Create count sessions
Upload MASTER baseline (morning snapshot)
Upload CURRENT baseline (refresh anytime)
View real-time dashboard
Export variance reports
Manage staff users

Staff/Counter (Level 3)

Select active count session
Scan locations and lots
Enter weights
Edit/delete their own scans
View their progress

🔄 Core Workflow

Phase 1: Session Setup (Admin)

Log in as admin
Create new count session:
- Session name: "January 17, 2026 - Daily Cycle Count"
- Type: Cycle Count OR Full Physical Inventory
Upload MASTER baseline CSV from NetSuite:
- Format: Item, Description, Lot Number, Location, Bin Number, On Hand
- Creates baseline version 1
Session status: Active
Counters can now begin

Phase 2: Counting (Staff)

Log in as staff
Select active session
Scan location barcode (e.g., R903B)
- System marks location "in progress"
- Shows: "Counting R903B"
Scan lot barcode
System checks lot against MASTER baseline:
- ✅ MATCH: Expected here, location correct
- ⚠️ WRONG LOCATION: Lot exists but system says different location
- ❌ GHOST LOT: Not in system at all
Enter weight
Save → returns to scan input (autofocus)
Repeat for all lots in location
Click "Finish Location"

Phase 3: Admin Monitoring

Real-Time Dashboard Shows:

Total locations & completion percentage
Active counters with current location
Variance summary (matches, wrong locations, missing, ghost lots)

Optional CURRENT Baseline Refresh:

Admin uploads new CSV from NetSuite
System recalculates CURRENT status for all scans
Shows what changed in system after count
Proves count was correct, lot moved later

📊 CSV Import Format

Required columns:

Item,Description,Lot Number,Location,Bin Number,On Hand
100001,Beef MDM,20260108-132620-PO25146,Wisconsin G & H,R903B,2030
100001,Beef MDM,20260108-132700-PO25146,Wisconsin G & H,R903B,2030
100001,Beef MDM,20260106-150649-PO24949,Wisconsin G & H,R905C,2065

Column Descriptions:

Item: SKU or item number
Description: Product description
Lot Number: Unique lot identifier
Location: Warehouse location name
Bin Number: Specific bin/rack location code
On Hand: Current quantity in pounds

🎯 Key Features

Dual Baseline System

MASTER Baseline:

Uploaded once at session start (e.g., 6:00 AM)
Never changes during session
What counters validate against
Represents "what should have been there when we started"

CURRENT Baseline:

Admin can refresh unlimited times
Only affects admin dashboard/reporting
Counters never see it
Shows "where is it in the system NOW"
Identifies movement after count

Variance Detection

Perfect Match: Right location, weight within tolerance
Weight Variance: Right location, weight differs (calculates %)
Wrong Location: Lot exists but scanned in different location
Ghost Lot: Scanned but not in baseline at all
Missing/Phantom: In baseline but not found during count

Blind Counting

Counters don't see expected quantities
Prevents bias
Ensures honest count

Real-Time Dashboard

Active counters with current location
Progress by location
Variance counts updating live
Dual view (MASTER vs CURRENT) after refresh

Audit Trail

Every scan timestamped with user
Soft deletes tracked
Edits tracked with modified timestamp
Baseline version tracking

🗂️ Database Schema

Tables:

Users: Authentication and role management
CountSessions: Count session metadata
BaselineInventory_Master: Morning baseline (never changes)
BaselineInventory_Current: Refreshable baseline (soft delete)
LocationCounts: Location-by-location progress
ScanEntries: Every lot scan with dual status tracking
MissingLots: Expected lots not found

Indexes:

Optimized for fast lookups on lot numbers, locations, and statuses.

🔧 Technology Stack

Backend: Python 3.13 + Flask
Database: SQLite
Frontend: HTML5 + CSS3 + Vanilla JavaScript
Templates: Jinja2

📂 Project Structure

scanlook/
├── app.py                 # Main Flask application
├── database/
│   ├── init_db.py         # Database initialization
│   └── scanlook.db        # SQLite database (created)
├── static/
│   ├── css/
│   │   └── style.css      # Main stylesheet
│   └── js/
│       └── main.js        # Client-side JavaScript
└── templates/
    ├── base.html          # Base template
    ├── login.html         # Login page
    ├── admin_dashboard.html
    ├── staff_dashboard.html
    ├── create_session.html
    ├── session_detail.html
    ├── count_session.html
    └── count_location.html

🎨 Design Philosophy

Mobile-First, Warehouse-Optimized:

High contrast dark theme for warehouse lighting
Large touch targets (44px minimum)
Autofocus on scan inputs
Scanner trigger = Enter key
Visual feedback with color-coded statuses
Minimal typing required

Color Coding:

✅ Green: Perfect match
⚠️ Yellow: Wrong location
❌ Red: Missing or ghost lot
🔵 Blue: Weight variance

🚧 Current Status: Phase 1 Complete (MVP)

✅ Implemented:

User authentication (3 roles)
Session creation
MASTER baseline upload
Location scanning
Lot scanning with MASTER status
Weight entry
Basic dashboard
Real-time progress tracking
Mobile-optimized UI

🔜 Next Phases:

Phase 2: CURRENT baseline refresh & dual status recalculation
Phase 3: Missing lot detection, enhanced dashboard
Phase 4: Excel export with multiple tabs
Phase 5: Data retention automation, user management
Phase 6: Docker deployment

📝 Development Notes

Default Accounts (Testing)

All passwords should be changed in production!

Security Considerations

Passwords are hashed with Werkzeug
Session management via Flask sessions
SQL injection prevention (parameterized queries)
Soft deletes preserve audit trail

Data Retention

Plan: Keep data for 30 days
Nightly cleanup job (to be implemented)
Archive old sessions

🎯 Success Metrics

Current State (Year-End Physical):

Duration: 5 days
Data entry: Manual, error-prone
Variance resolution: Weeks later

Target State (with ScanLook):

Duration: 1 weekend (2 days max)
Data entry: Zero (all scanned)
Variance resolution: Real-time flagging
Accuracy: 99%+ (no handwriting errors)
Time savings: 60%+

💡 Future Enhancements

Multi-branch support
Direct NetSuite API integration
Photo capture for variance proof
Barcode generation for location labels
Native mobile apps
Offline mode with sync

📧 Support

This is a custom internal tool. Contact your system administrator for support.

Built with ❤️ for efficient inventory management

Inspired by BomLook from the FoxPro days 🚀

8.3 KiB Raw Blame History