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

```bash
# Make sure web dependencies are installed
uv sync
```

### 2. Run the Web Server

```bash
# 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`

```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:
   ```bash
   # 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:

```nginx
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`:
```python
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

```bash
# 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