Cannabis Inventory Management System

A production React application for cannabis inventory tracking, barcode scanning, and thermal label generation. Handles multi-source CSV/Excel imports, automatic allergen detection, and Zebra ZT610-optimized label printing at 203 DPI. Cloud-synced master product list via Supabase with offline localStorage fallback.

Running in production since 2024. Currently at v7.4.1.

Table of Contents

• Features
• Tech Stack
• Prerequisites
• Setup
• Environment Configuration
• Authentication
• Data Sources
• Label Generation
• Thermal Printer Configuration
• Development
• Build
• Production Deployment
• Security Notes

Features

• Multi-Source Data Import: Support for Main Inventory, Sweed Reports, and Import Report CSV/Excel files
• User Authentication: Role-based access control with configurable user credentials
• Barcode Scanning: Real-time barcode scanning with product lookup across all data sources
• Thermal Label Generation: Professional labels optimized for Zebra ZT610 (4" × 6" thermal labels)
• Automatic Allergen Detection: Smart detection of allergen-containing products based on product names
• Enhanced Data Management: Batch IDs, harvest/package dates, case quantities, and box tracking
• Real-Time Session Tracking: Track scanned items and generate comprehensive reports
• Multi-Format Support: CSV and Excel file import with robust error handling
• Responsive Dark UI: Modern dark theme optimized for warehouse environments
• Label Preview: Live preview of labels before printing
• Calibration Tools: Printer alignment testing and calibration utilities
• Master List Cloud Sync: Supabase-backed product list with 1000+ record pagination
• Unmapped Product Admin: Override system for unrecognized products with remap history
• Multi-Location Support: HSTD (horizontal) and MTD (vertical) label formats
• Version-Aware State: Automatic cache invalidation on app updates

---

Tech Stack

Layer	Technology
Frontend	React 18, React Router 6
Build	Vite 5
Styling	Tailwind CSS 3.4 (custom dark theme, 400+ lines)
Labels	jsPDF (PDF generation), JsBarcode (Code 39)
Data Import	PapaParse (CSV), SheetJS (Excel)
Cloud Sync	Supabase (PostgreSQL, master product list)
Printer	Zebra Browser Print SDK (ZPL generation)
Hosting	Netlify (SPA routing, security headers, asset caching)

Prerequisites

Before setting up the project, ensure you have the following:

• Node.js (v18+) and npm: Install from nodejs.org
• Modern Web Browser: Chrome, Firefox, Safari, or Edge
• Zebra ZT610 Thermal Printer (optional): For physical label printing
• Label Stock: 4" × 6" thermal labels compatible with Zebra ZT610
• Git: For cloning the repository

Setup

Follow these steps to set up the project locally:

1. Clone the Repository

git clone https://github.com/claygeo/cannabis-inventory-system.git
cd cannabis-inventory-system

2. Install Dependencies

npm install

3. Environment Configuration

Copy the environment template and configure your credentials:

cp .env.example .env

Edit the .env file with your preferred settings. For quick testing, the default demo credentials will work immediately.

4. Start the Development Server

npm run dev

The application will be available at http://localhost:3000

5. Build for Production

npm run build

Environment Configuration

The application uses environment variables for user authentication. This allows you to:

• Keep production credentials secure
• Use different credentials for different environments
• Share the project publicly without exposing sensitive data

Demo Configuration (Default)

If no environment variables are set, the system uses demo credentials:

Username	Password	Role	Purpose
admin	admin123	Administrator	Full system access
warehouse	warehouse123	Warehouse	Basic scanning operations
manager	manager123	Manager	Management functions

Custom Configuration

Set up your own user accounts by editing the .env file:

# Example custom user
VITE_USER_JOHN_PASSWORD=secure_password_123
VITE_USER_JOHN_ROLE=Administrator
VITE_USER_JOHN_FULL_NAME=John Smith
VITE_USER_JOHN_DISPLAY_NAME=John

Available Roles

• Administrator: Full system access, can import data and generate reports
• Manager: Management functions, reporting, and label generation
• Warehouse: Basic scanning and inventory operations

Authentication

The application uses a frontend-only authentication system designed for:

• Demo purposes: Easy testing and development
• Internal networks: Controlled access environments
• Proof of concept: Showcasing functionality

Security Considerations

Important: This is a demonstration-grade authentication system:

• Passwords are stored in environment variables (visible to frontend)
• No server-side validation or session management
• Suitable for internal tools and demos only
• For production use, implement proper backend authentication

Data Sources

The system supports multiple inventory data sources:

Import Report Format

• File Type: CSV or Excel
• Required Columns:
  • Column A: Product Name
  • Column D: Quantity on Hand
  • Column E: Barcode Number
  • Column F: External Barcode (optional)
• Header Row: Row 1 (index 0)
• Data Starts: Row 2 (index 1)

File Upload Process

1. Login with appropriate credentials
2. Navigate to Import Report page
3. Select file (CSV or Excel format)
4. Validate data structure and content
5. Import processed data into the system

Label Generation

Thermal Printer Mode (Default)

• Format: Single 4" × 6" labels per page
• Orientation: Horizontal landscape
• Content: Optimized layout with brand separation
• Printer: Optimized for Zebra ZT610 (203 DPI)

Label Features

• Brand Detection: Automatic separation of brand and product names
• Allergen Warnings: Visual warnings for allergen-containing products
• Enhanced Layout:
  • Large product names (up to 48pt font)
  • Package ID reference box
  • Harvest and package dates
  • Case quantity and box tracking
  • Batch ID squares
  • Audit trail with timestamp and user

Calibration and Testing

• Alignment Test: Generate calibration pages for printer setup
• Blank Templates: Empty label borders for custom projects
• Test Labels: Single and full-sheet test patterns

Thermal Printer Configuration

Zebra ZT610 Setup

1. Label Size: Configure for 4" × 6" (288 × 432 points)
2. Print Mode: Thermal Transfer or Direct Thermal
3. DPI Setting: 203 DPI
4. Media Settings: Continuous media, no gaps
5. Calibration: Use built-in alignment test pages

Print Settings

• Page Size: Actual Size (no scaling)
• Orientation: Portrait
• Margins: None (full bleed)
• Quality: High/Best quality

Development

Project Structure

src/
├── components/          # React components
├── contexts/           # React context providers
├── hooks/              # Custom React hooks
├── utils/              # Utility functions
├── styles/             # CSS and styling
└── constants.js        # Application constants

Development Scripts

npm run dev      # Start development server
npm run build    # Build for production
npm run preview  # Preview production build
npm run lint     # Run ESLint

---

Build

Production build via Vite with manual chunk splitting for optimal caching.

Chunk	Raw	Gzip
react	141 KB	45 KB
utils (papaparse, jsbarcode, jspdf, xlsx)	872 KB	281 KB
html2canvas	201 KB	48 KB
app code	482 KB	118 KB
router	21 KB	8 KB
ui (lucide, toast)	22 KB	8 KB
CSS	101 KB	14 KB

CI pipeline runs on every push and PR to master: npm ci and npm run build.

---

Production Deployment

Environment Setup

1. Create production .env file:

   cp .env.example .env
   # Edit .env with production credentials

2. Build the application:

   npm run build

3. **Deploy the dist folder` to your web server

Recommended Hosting

• Static hosting: Netlify, Vercel, GitHub Pages
• Web servers: Apache, Nginx, IIS
• CDN: CloudFront, CloudFlare

Production Considerations

• HTTPS: Always use HTTPS in production
• Environment Variables: Keep credentials secure
• Browser Support: Test with target browsers
• Data Backup: Implement localStorage backup strategies
• Access Control: Consider network-level restrictions

Security Notes

Authentication Limitations

This system uses frontend-only authentication which is appropriate for:

Good for:

• Internal company tools
• Demo applications
• Development and testing
• Controlled network environments

Not suitable for:

• Public-facing applications
• Multi-tenant systems
• Applications handling sensitive data
• Compliance-required environments

Recommended Security Upgrades

For production systems handling sensitive data:

1. Backend Authentication: Implement server-side user management
2. Database Storage: Use proper database instead of localStorage
3. API Security: Add authentication tokens and rate limiting
4. Access Controls: Implement proper role-based permissions
5. Audit Logging: Add comprehensive activity logging
6. Data Encryption: Encrypt sensitive data at rest and in transit

Browser Storage

All data is stored locally in browser localStorage:

• Inventory Data: Main inventory, Sweed data, Import reports
• Scanned Items: Session tracking of scanned products
• Enhanced Data: Label configuration settings
• User Sessions: Authentication and activity logging
• Session History: Comprehensive activity tracking

Workflow

1. Setup: Copy .env.example to .env and configure
2. Login: Authenticate with configured credentials
3. Import Data: Upload inventory files from CSV/Excel sources
4. Scan Products: Use barcode scanner or manual entry to track items
5. Configure Labels: Set quantities, dates, batch IDs, and enhanced data
6. Generate Labels: Preview and print thermal labels
7. Session Management: Track progress and generate reports

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

For support and questions:

• Issues: Create a GitHub issue for bugs or feature requests
• Documentation: Check the README and inline code comments
• Security: For security-related issues, please email privately

Changelog

v7.4.1

• Unmapped products admin dashboard with remap history
• Fix dark theme consistency on admin pages

v7.3.0

• Supabase cloud sync for master product list
• Pagination support for 1000+ products
• Auto-fix strain placeholder with actual strain data

v5.5.0

• Environment variable configuration for credentials
• Enhanced documentation and setup process