inventree-stock-tool/WEB_APP.md

InvenTree Stock Tool - Web Application

A modern web-based interface for InvenTree barcode scanning and inventory management.

Features

• Modern Web UI: Responsive design works on desktop, tablet, and mobile
• Real-time Updates: WebSocket integration for live import progress
• No Installation Required: Just open in any modern browser
• Multi-User Support: Multiple users can access simultaneously
• Camera Barcode Scanning: Use device camera or USB scanner
• Async Part Import: Non-blocking background imports with visual feedback
• Dark Theme: Eye-friendly dark interface

Quick Start

1. Install Dependencies

# Make sure web dependencies are installed
uv sync

2. Run the Web Server

# Using UV (recommended)
uv run stock-tool-web

# Or directly
uv run python -m stocktool.web.app

3. Open in Browser

Navigate to: http://localhost:5000

The web server will be accessible from any device on your local network at: http://YOUR_IP_ADDRESS:5000

Usage

Location Setup

1. Scan Location Barcode: Enter location barcode (INV-SL format) in the location field
2. Or Select from Dropdown: Choose from the list of available locations

Select Mode

Click one of the four operation modes:

• Add Stock - Add new stock or increase quantity
• Update Stock - Set exact stock quantity
• Check Stock - View current stock level
• Locate Part - Find all locations where part is stored

Scan Parts

1. Click in the "Scan Part" field or just start scanning
2. Scan barcode or type part code
3. Press Enter or click "Process"

Pending Imports

When unknown parts are scanned:

• They appear in the "Pending Imports" section
• Import runs in background (30s timeout)
• You can continue scanning other parts
• Part is auto-processed when import completes
• Failed imports retry automatically (up to 3 times)

Activity Log

• Shows all operations in real-time
• Color-coded messages:
  • 🔵 Blue: Info
  • 🟢 Green: Success
  • 🟡 Yellow: Warning
  • 🔴 Red: Error

Barcode Commands

Scan special barcodes to control the app:

Mode Switching:

• MODE:ADD, IMPORT → Switch to Add Stock mode
• MODE:UPDATE, UPDATE → Switch to Update Stock mode
• MODE:CHECK, CHECK → Switch to Check Stock mode
• MODE:LOCATE, LOCATE → Switch to Locate Part mode

Location:

• CHANGE_LOCATION, LOCATION → Clear current location

Supported Barcode Formats

1. JSON-like: {PM:PART-CODE,QTY:10}
2. Separator-based: Uses GS/RS separators (\x1D, \x1E)
3. InvenTree locations: INV-SL<location_id>

API Endpoints

The web app exposes a RESTful API:

Configuration

• GET /api/config - Get app configuration

Locations

• GET /api/locations - List all locations

Parts

• POST /api/part/search - Search for a part
• POST /api/part/import - Queue part for import
• POST /api/part/locate - Find part locations

Stock Operations

• POST /api/stock/add - Add stock
• POST /api/stock/update - Update stock quantity
• POST /api/stock/check - Check stock level

Pending Imports

• GET /api/pending - Get pending imports list

WebSocket Events

Real-time events via Socket.IO:

Server → Client:

• connected - Connection established
• barcode_parsed - Barcode successfully parsed
• import_complete - Part import finished successfully
• import_retry - Import failed, retrying
• import_failed - Import failed after all retries

Client → Server:

• parse_barcode - Parse a barcode string

Technology Stack

• Backend: Flask + Flask-SocketIO
• Frontend: HTML5 + TailwindCSS + Alpine.js
• Real-time: WebSocket (Socket.IO)
• Icons: Font Awesome 6
• Barcode: Keyboard input (camera support coming soon)

Configuration

Uses the same configuration file as the desktop app:

Location: ~/.config/scan_and_import.yaml

host: https://your-inventree-server.com
token: your-api-token-here

Network Access

Local Network Access

To access from other devices on your network:

1. Find your computer's IP address:

   # Windows
   ipconfig
   
   # Linux/Mac
   ifconfig
   

2. Open browser on any device:

   http://YOUR_IP_ADDRESS:5000
   

Production Deployment

For production use, consider:

1. Reverse Proxy: Use nginx or Apache
2. HTTPS: Enable SSL/TLS for security
3. Process Manager: Use systemd or supervisor
4. Firewall: Configure appropriate access rules

Example nginx config:

server {
    listen 80;
    server_name stock-tool.local;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

Troubleshooting

Port Already in Use

Change the port in app.py:

socketio.run(app, host='0.0.0.0', port=5001, ...)

WebSocket Connection Failed

Check your firewall settings allow port 5000.

Slow Import Performance

The import uses inventree-part-import which can be slow. This is normal. The web UI stays responsive while imports run in background.

Comparison: Web vs Desktop

Feature	Web App	Desktop App
Installation	None (browser only)	Python + dependencies
Platform	Any (browser)	Windows/Linux/Mac
Multi-user	Yes	No
Mobile friendly	Yes	No
Camera scanning	Coming soon	No
Async imports	Yes	Yes
Real-time updates	WebSocket	UI updates
Deployment	Server-based	Local install

Development

Run in Debug Mode

# Flask debug mode is enabled by default
uv run stock-tool-web

Customize UI

Edit files in:

• src/stocktool/web/templates/ - HTML templates
• src/stocktool/web/static/js/ - JavaScript
• src/stocktool/web/static/css/ - CSS (uses Tailwind CDN)

Add New Endpoints

Edit src/stocktool/web/app.py and add route handlers.

License

MIT License - Same as the main project