Lager Guru Docs

Appearance

Lager Guru - Complete Documentation ​

Official documentation for Lager Guru WMS - Enterprise-grade warehouse management and transport orchestration system with multi-tenant SaaS architecture.

🌐 Live Documentation: https://docs-lager-guru.hashmatrix.de/

Table of Contents ​

Overview ​

Lager Guru is a comprehensive warehouse management system (WMS) designed for modern logistics operations. It provides real-time inventory tracking, intelligent routing, automated picking workflows, and complete visibility into warehouse operations.

What is Lager Guru? ​

Lager Guru is a Progressive Web Application (PWA) that combines:

  • Warehouse Management: Complete inventory tracking, pick & pack operations, zone management
  • Transport Orchestration: Driver assignment, GPS tracking, route optimization
  • Multi-Tenant SaaS: Complete tenant isolation with Row-Level Security (RLS)
  • Enterprise Features: SSO integration, advanced analytics, AI-powered optimization

Key Benefits ​

  • ✅ Real-time Updates: Supabase Realtime for live data synchronization
  • ✅ PWA Support: Installable, offline-capable progressive web application
  • ✅ Multi-Tenant: Complete data isolation with RLS policies
  • ✅ Enterprise SSO: OIDC/SAML integration for enterprise authentication
  • ✅ AI-Powered: Intelligent routing, slotting optimization, and auto-assignment
  • ✅ Scalable: Built on Supabase for automatic scaling
  • ✅ Modern Stack: React 18, TypeScript, Vite

Quick Start ​

Prerequisites ​

  • Node.js 18+
  • npm or yarn
  • Supabase account
  • Docker (for deployment)

Installation ​

bash
# Clone repository
git clone https://github.com/Pepinko81/lager-guru.git
cd lager-guru

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your Supabase credentials

# Start development server
npm run dev

Development Commands ​

bash
# Run development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Generate documentation
npm run docs:dev
npm run docs:build

Features ​

Core Functionality ​

Multi-Role System ​

  • Admin: Full system access, tenant management
  • Tenant Admin: Full tenant access, user management
  • Tenant User: Standard operations, limited admin
  • Inventory Worker: Inventory, Pick & Pack, Floor Plan (view)
  • Maintenance Worker: Maintenance, Equipment Tracking
  • Driver: Shipment status, safety warnings

Real-time Updates ​

  • Supabase Realtime for live data synchronization
  • WebSocket-based updates
  • Automatic UI refresh on data changes

PWA Support ​

  • Installable on mobile and desktop
  • Offline-capable with service workers
  • Push notifications support
  • App-like experience

Barcode Scanning ​

  • Camera-based barcode scanning
  • Quick order lookup
  • Inventory item identification
  • Web-based scanning API

GPS Tracking ​

  • Live driver location tracking
  • Interactive map visualization
  • Real-time position updates
  • Route history

AI Suggestions ​

  • Intelligent driver assignment
  • Zone assignment recommendations
  • Multi-factor scoring (distance, capacity, availability)

Shift Management ​

  • Weekly/monthly shift scheduling
  • Shift templates
  • Automatic status sync
  • Shift hours analytics

Analytics ​

  • Real-time KPIs
  • Advanced reporting
  • Shift hours tracking
  • Performance metrics

Enterprise Modules ​

Inventory / Stock Management ​

  • Real-time stock tracking with complete audit trail
  • Zone-based inventory organization
  • Low stock alerts and automated reordering
  • Barcode scanning integration
  • Stock movement history (inbound, outbound, transfer, adjustment)

Pick & Pack ​

  • Automated pick list generation
  • Optimal route calculation using zone coordinates
  • Real-time picking progress tracking
  • Pack session management
  • Integration with inventory for automatic stock updates

Warehouse Floor Plan ​

  • Interactive SVG-based floor plan editor
  • Real-time zone utilization heatmaps
  • Driver and equipment location tracking
  • Safety overlay visualization
  • Pick route visualization

Slotting Optimization AI ​

  • AI-driven zone placement recommendations
  • Movement velocity analysis
  • Turnover rate optimization
  • Congestion factor calculation
  • Heatmap-based zone utilization

Auto Assignment Engine ​

  • Intelligent driver-to-shipment matching
  • Multi-factor scoring (distance, capacity, availability)
  • Zone-based assignment optimization
  • Real-time assignment suggestions
  • Manual override capabilities

Maintenance Module ​

  • Equipment maintenance scheduling
  • Task tracking and completion
  • Maintenance history and analytics
  • Preventive maintenance alerts
  • Integration with equipment tracking

Safety & Compliance ​

  • Incident reporting and tracking
  • Safety zone visualization
  • Compliance checklist management
  • Analytics and reporting
  • Integration with warehouse map

Equipment Tracking ​

  • QR/RFID/manual equipment location tracking
  • Real-time equipment status
  • Location history
  • Integration with floor plan visualization

Technology Stack ​

Frontend ​

  • React 18 - UI library with latest features
  • TypeScript - Type safety and better DX
  • Vite - Fast build tool and dev server
  • shadcn/ui - High-quality component library
  • Tailwind CSS - Utility-first CSS framework
  • React Router v6 - Client-side routing
  • Framer Motion - Smooth animations
  • Recharts - Data visualization
  • MapLibre GL - Interactive maps
  • @zxing/browser - Barcode scanning

Backend ​

  • Supabase - Backend-as-a-Service
    • PostgreSQL database
    • Realtime subscriptions (WebSocket)
    • Authentication (JWT)
    • Row-Level Security (RLS)
    • Edge Functions (Deno)
    • Storage (file uploads)

Deployment ​

  • Docker - Containerization
  • Nginx - Web server and reverse proxy
  • GitHub Actions - CI/CD automation
  • GitHub Container Registry - Docker image hosting

Build Tools ​

  • Vite - Module bundler
  • TypeScript - Type checking
  • ESLint - Code linting
  • Workbox - Service worker generation

Architecture ​

System Architecture ​

┌─────────────────────────────────────────────────────────────┐
│                     Client (Browser)                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   React App  │  │  Service     │  │   PWA        │      │
│  │   (Vite)     │  │  Worker      │  │   Manifest   │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ HTTPS
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    Supabase Backend                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │  PostgreSQL  │  │  Realtime    │  │    Auth      │      │
│  │  Database    │  │  Subscriptions│  │  (JWT)      │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│  ┌──────────────┐  ┌──────────────┐                         │
│  │  Edge       │  │  Storage     │                         │
│  │  Functions  │  │  (Files)     │                         │
│  └──────────────┘  └──────────────┘                         │
└─────────────────────────────────────────────────────────────┘

Project Structure ​

lager-guru/
├── src/
│   ├── components/        # React components
│   │   ├── admin/        # Admin-specific components
│   │   ├── dashboard/     # Dashboard components
│   │   ├── worker/        # Worker components
│   │   └── ui/            # Reusable UI components
│   ├── contexts/          # React context providers
│   ├── hooks/             # Custom React hooks
│   ├── integrations/      # External service integrations
│   ├── lib/               # Utility functions
│   ├── pages/             # Page components
│   └── config/            # Configuration
├── supabase/
│   ├── migrations/        # Database migrations
│   └── functions/         # Edge Functions
├── docs/                  # Documentation (VitePress)
├── public/                # Static assets
└── scripts/               # Build and utility scripts

Data Flow ​

Authentication Flow ​

  1. User logs in via Supabase Auth
  2. JWT token stored in browser
  3. Token sent with all API requests
  4. RLS policies enforce access control

Real-time Updates ​

  1. Client subscribes to Supabase Realtime channels
  2. Database changes trigger events
  3. Client receives updates via WebSocket
  4. UI updates automatically

State Management ​

  • React Context - Global state (auth, branding)
  • React Query - Server state caching
  • Local State - Component-specific state
  • Supabase Realtime - Real-time synchronization

Security Model ​

  • Row-Level Security (RLS): Database-level tenant isolation
  • JWT Authentication: Secure token-based auth
  • Tenant Context: Automatic tenant filtering
  • Service Role: Secure backend operations only
  • SSO Integration: Enterprise identity providers

Installation & Setup ​

Local Development Setup ​

  1. Clone the repository

    bash
    git clone https://github.com/Pepinko81/lager-guru.git
cd lager-guru

  2. Install dependencies

    bash
    npm install

  3. Configure environment variables

    bash
    cp .env.example .env

    Edit .env with your Supabase credentials:

    env
    VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=your-anon-key
VITE_WEB_PUSH_PUBLIC_KEY=your-vapid-public-key

  4. Start development server

    bash
    npm run dev

  5. Access the application

    • Open http://localhost:5173 in your browser

Production Build ​

bash
# Build for production
npm run build

# Preview production build
npm run preview

Database Setup ​

  1. Create Supabase project

    • Go to supabase.com
    • Create a new project
    • Note your project URL and anon key

  2. Run migrations

    bash
    # Using Supabase CLI
supabase db push

# Or manually via Supabase dashboard
# Copy SQL from supabase/migrations/ and run in SQL editor

  3. Configure RLS policies

    • RLS policies are included in migrations
    • Verify policies are active in Supabase dashboard

Enterprise Modules ​

Inventory / Stock Management ​

Complete enterprise-grade inventory tracking and stock movement management.

Features:

  • Master data management (SKU, name, description)
  • Real-time quantity tracking
  • Stock movement audit trail (inbound, outbound, adjustment, transfer)
  • Low stock warnings
  • Zone-based organization
  • Barcode scanning integration

Database Tables:

  • inventory_items - Item master data
  • stock_movements - Complete audit trail

Key Functions:

  • Create/update/delete items
  • Record stock movements
  • Query low stock items
  • Get movement history

Pick & Pack ​

Enterprise WMS-style picking and packing with optimal route calculation.

Features:

  • Automated pick list generation
  • Optimal route calculation using zone coordinates
  • Real-time picking progress tracking
  • Pack session management
  • Integration with inventory for automatic stock updates

Database Tables:

  • pick_lists - Pick list master
  • pick_list_items - Items to pick
  • pack_sessions - Packing operations

Key Functions:

  • Create pick list from orders
  • Calculate optimal pick route
  • Track picking progress
  • Complete pack session

Warehouse Floor Plan ​

SVG-based zone layout visualization with real-time updates.

Features:

  • Interactive SVG-based floor plan editor
  • Real-time zone utilization heatmaps
  • Driver and equipment location tracking
  • Safety overlay visualization
  • Pick route visualization

Key Functions:

  • Edit floor plan layout
  • Visualize zone utilization
  • Track equipment locations
  • Display safety zones

Slotting Optimization AI ​

AI-driven zone placement recommendations based on movement patterns.

Features:

  • Zone suitability scoring
  • Movement velocity analysis
  • Reorganization recommendations
  • Heatmap generation
  • Impact score calculation

Key Functions:

  • Analyze movement patterns
  • Calculate zone suitability
  • Generate recommendations
  • Estimate impact of changes

Auto Assignment Engine ​

Intelligent driver-to-shipment matching with multi-factor scoring.

Features:

  • Multi-factor driver scoring (distance, capacity, availability)
  • Zone-based optimization
  • Distance-based routing
  • Capacity consideration
  • Real-time suggestions

Key Functions:

  • Score drivers for shipments
  • Suggest optimal assignments
  • Consider zone proximity
  • Factor in driver capacity

Maintenance Module ​

Equipment maintenance tracking and scheduling.

Features:

  • Equipment maintenance scheduling
  • Task tracking and completion
  • Maintenance history and analytics
  • Preventive maintenance alerts
  • Integration with equipment tracking

Database Tables:

  • maintenance_tasks - Maintenance tasks
  • maintenance_history - Completed tasks

Safety & Compliance ​

Incident reporting and safety zone management.

Features:

  • Incident reporting and tracking
  • Safety zone visualization
  • Compliance checklist management
  • Analytics and reporting
  • Integration with warehouse map

Database Tables:

  • safety_incidents - Incident records
  • safety_zones - Safety zone definitions

Equipment Tracking ​

QR/RFID/manual equipment location tracking.

Features:

  • Location tracking (QR/RFID/manual)
  • Real-time status
  • History tracking
  • Floor plan integration

Database Tables:

  • equipment - Equipment master data
  • equipment_locations - Location history

Multi-Tenant Architecture ​

Overview ​

Lager Guru implements a comprehensive multi-tenant SaaS architecture that allows multiple organizations (tenants) to use the same application instance while maintaining complete data isolation and security.

Core Principles ​

  1. Tenant ID Everywhere: All business data tables include tenant_id
  2. RLS Enforcement: Database-level security policies enforce tenant isolation
  3. Automatic Filtering: Application code automatically filters by tenant
  4. Service Role Bypass: Background jobs use service role to bypass RLS when needed

Key Components ​

Tenant Table ​

  • id: Unique tenant identifier (UUID)
  • name: Tenant/organization name
  • company: JSONB field for additional company metadata
  • active: Whether the tenant is active

Tenant Users Table ​

  • tenant_id: Reference to tenant
  • user_id: Reference to user profile
  • role: Either tenant_admin or tenant_user
  • Unique constraint on (tenant_id, user_id)

Data Isolation Strategy ​

Row-Level Security (RLS) ​

RLS policies automatically filter queries based on the authenticated user's tenant:

sql
-- Example: Users can only see their tenant's shipments
CREATE POLICY shipments_tenant_isolation ON shipments
  FOR SELECT
  USING (
    tenant_id IN (
      SELECT tenant_id FROM tenant_users
      WHERE user_id = auth.uid()
    )
  );

Application-Level Filtering ​

The application code automatically includes tenant filtering:

typescript
// Automatically filters by current user's tenant
const { data } = await supabase
  .from('shipments')
  .select('*')
  // tenant_id is automatically filtered by RLS

User Roles ​

Super Admin ​

  • Role: admin in user_roles table
  • Access: Can see and manage ALL tenants
  • Use Case: Platform administrators

Tenant Admin ​

  • Role: tenant_admin in tenant_users table
  • Access: Full access to their tenant's data
  • Use Case: Organization administrators

Tenant User ​

  • Role: tenant_user in tenant_users table
  • Access: Read/write access to their tenant's data (with module-specific restrictions)
  • Use Case: Regular employees

Tenant Lifecycle ​

  1. Creation: Super admin creates new tenant
  2. User Assignment: Users are assigned to tenant via tenant_users
  3. Data Isolation: All data automatically scoped to tenant
  4. Deactivation: Tenant can be deactivated without data deletion
  5. Deletion: Cascade deletion removes all tenant data (if needed)

Security Guarantees ​

  1. Database-Level: RLS policies prevent cross-tenant queries
  2. Application-Level: Code always includes tenant context
  3. Service Role: Only used for background jobs, never for user requests
  4. Audit Trail: All operations logged with tenant context

Performance Considerations ​

  • Indexes: tenant_id columns are indexed for fast filtering
  • Query Optimization: RLS policies use efficient subqueries
  • Caching: Tenant context cached in application state
  • Batch Operations: Service role used for bulk operations

SSO Integration ​

OpenID Connect (OIDC) ​

Enterprise SSO support via OpenID Connect protocol.

Configuration Steps ​

  1. Obtain OIDC Provider Information

    • Issuer URL
    • Client ID
    • Client Secret
    • Metadata URL (optional)

  2. Configure in Lager Guru

    • Navigate to System Settings → SSO Integration
    • Add new OIDC provider
    • Enter provider details
    • Toggle Active to enable

  3. Configure Redirect URI in OIDC Provider

    https://your-domain.com/auth/callback/oidc?provider_id={provider_id}&tenant_id={tenant_id}

Authentication Flow ​

  1. User clicks "Mit Unternehmens-SSO anmelden" on login page
  2. User is redirected to OIDC provider's authorization endpoint
  3. User authenticates with OIDC provider
  4. OIDC provider redirects back to Lager Guru with authorization code
  5. Lager Guru exchanges code for tokens
  6. User information is extracted from ID token
  7. User is automatically provisioned into tenant (if new)
  8. User is signed in and redirected to dashboard

User Provisioning ​

When a user logs in via SSO for the first time:

  • A user account is automatically created in Lager Guru
  • The user is assigned to the tenant that initiated the SSO flow
  • Default role: tenant_user (can be changed by tenant admin)

Security Considerations ​

  • State Parameter: OIDC flow uses state parameter to prevent CSRF attacks
  • PKCE: Authorization Code flow with PKCE is used for enhanced security
  • Token Validation: All tokens are validated against the OIDC provider
  • Tenant Isolation: Users can only be provisioned into the tenant that initiated the SSO flow

SAML Integration ​

Enterprise SSO support via Security Assertion Markup Language (SAML) protocol.

Configuration Steps ​

  1. Obtain SAML Provider Information

    • Entity ID / Issuer
    • SSO URL
    • Certificate (X.509)
    • Attribute mappings

  2. Configure in Lager Guru

    • Navigate to System Settings → SSO Integration
    • Add new SAML provider
    • Enter provider details
    • Configure attribute mappings
    • Toggle Active to enable

  3. Configure Assertion Consumer Service (ACS) URL in SAML Provider

    https://your-domain.com/auth/callback/saml?provider_id={provider_id}&tenant_id={tenant_id}

Supported Providers ​

  • Azure AD
  • Okta
  • Auth0
  • Keycloak
  • Any OIDC/SAML-compliant identity provider

API Reference ​

Overview ​

Complete TypeScript API documentation for Lager Guru. All APIs are built on top of Supabase client with automatic tenant filtering via RLS.

Hooks ​

Custom React hooks for authentication, branding, and data management.

useAuth() ​

Authentication hook providing user and role information.

typescript
import { useAuth } from '@/contexts/AuthContext';

function MyComponent() {
  const { user, userRole, isLoading } = useAuth();
  // ...
}

useBranding() ​

Branding hook for tenant-specific branding.

typescript
import { useBranding } from '@/contexts/BrandingContext';

function MyComponent() {
  const { branding } = useBranding();
  // ...
}

Context Providers ​

React context providers for global state management.

  • AuthContext: User authentication and role management
  • BrandingContext: Tenant-specific branding configuration

Integrations ​

External service integrations including Supabase client setup.

Supabase Client ​

typescript
import { supabase } from '@/integrations/supabase/client';

// Query with automatic tenant filtering
const { data, error } = await supabase
  .from('shipments')
  .select('*')
  .eq('status', 'pending');

Utilities ​

Utility functions and helpers for common operations.

Inventory Functions ​

typescript
import { createItem, updateItem, recordMovement } from '@/lib/inventory';

// Create inventory item
const { data, error } = await createItem({
  sku: 'ITEM-001',
  name: 'Sample Product',
  zone_id: 'zone-uuid',
  min_quantity: 10,
});

Pick & Pack Functions ​

typescript
import { createPickList, calculateRoute } from '@/lib/pickpack';

// Create pick list
const { data, error } = await createPickList({
  items: [
    { item_id: 'item-uuid', qty: 5 },
  ],
});

Code Examples ​

See API Reference Documentation for detailed examples and full API documentation.

Deployment ​

Overview ​

Lager Guru is deployed using Docker and Nginx for production environments.

Prerequisites ​

  • Docker and Docker Compose installed
  • Nginx installed (for reverse proxy)
  • Domain name configured
  • SSL certificate (for HTTPS)

Docker Deployment ​

Build and Run ​

bash
# Build Docker image
docker build -t lager-guru:latest .

# Or use docker-compose
docker compose up -d --build

Environment Variables ​

Create a .env file:

bash
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=your-anon-key
VITE_WEB_PUSH_PUBLIC_KEY=your-vapid-public-key

Health Check ​

After deployment, verify the application is running:

bash
curl http://localhost/health.html

Nginx Configuration ​

Basic Configuration ​

See deploy/nginx.conf for basic configuration with:

  • Security headers
  • SPA routing support
  • Internal network restrictions

Production Configuration ​

For production, use deploy/nginx-lager-guru.hashmatrix.de.conf which includes:

  • SSL/TLS configuration
  • Domain-specific settings
  • Optimized caching

Setup Steps ​

  1. Copy configuration file:

    bash
    sudo cp deploy/nginx-lager-guru.hashmatrix.de.conf /etc/nginx/sites-available/lager-guru

  2. Create symbolic link:

    bash
    sudo ln -s /etc/nginx/sites-available/lager-guru /etc/nginx/sites-enabled/

  3. Test configuration:

    bash
    sudo nginx -t

  4. Reload Nginx:

    bash
    sudo systemctl reload nginx

SSL/TLS Setup ​

Using Certbot (Let's Encrypt) ​

bash
# Install Certbot
sudo apt-get install certbot python3-certbot-nginx

# Obtain certificate
sudo certbot --nginx -d your-domain.com

# Auto-renewal is configured automatically

Monitoring ​

Health Checks ​

Monitor the health endpoint:

bash
curl http://your-domain.com/health.html

Logs ​

View Docker logs:

bash
docker compose logs -f lager-guru

View Nginx logs:

bash
sudo tail -f /var/log/nginx/error.log

Security Checklist ​

  • [ ] HTTPS enabled with valid SSL certificate
  • [ ] Security headers configured
  • [ ] Environment variables secured
  • [ ] Database credentials protected
  • [ ] Firewall rules configured
  • [ ] Regular backups scheduled
  • [ ] Monitoring and alerting set up

CI/CD ​

Overview ​

Lager Guru uses GitHub Actions for continuous integration and deployment.

CI Pipeline ​

Triggers ​

  • Push to main or develop branches
  • Pull requests to main or develop

Steps ​

  1. Checkout code
  2. Setup Node.js 18
  3. Install dependencies (npm ci)
  4. TypeScript check
  5. ESLint
  6. Security audit
  7. Build
  8. Upload artifacts

CD Pipeline ​

Triggers ​

  • Push of version tag (e.g., v1.0.0)

Steps ​

  1. Build Docker image (multi-stage build)
  2. Push to GitHub Container Registry (GHCR)
  3. Deploy to server (SSH deployment)
  4. Health check

Creating a Release ​

  1. Update version in code

  2. Create git tag:

    bash
    git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

  3. GitHub Actions automatically:

    • Builds Docker image
    • Pushes to GHCR
    • Deploys to production
    • Runs health checks

Required Secrets ​

CI Secrets ​

  • VITE_SUPABASE_URL (optional)
  • VITE_SUPABASE_PUBLISHABLE_KEY (optional)

CD Secrets ​

  • VITE_SUPABASE_URL
  • VITE_SUPABASE_PUBLISHABLE_KEY
  • VITE_WEB_PUSH_PUBLIC_KEY (optional)
  • SSH_HOST
  • SSH_USER
  • SSH_KEY

Docker Images ​

Image Tags ​

  • ghcr.io/<owner>/lager-guru:<git-sha> - Commit SHA
  • ghcr.io/<owner>/lager-guru:latest - Latest
  • ghcr.io/<owner>/lager-guru:<version> - Version tag

Pulling Images ​

bash
docker pull ghcr.io/<owner>/lager-guru:latest

Troubleshooting ​

CI Failures ​

  • Check TypeScript errors
  • Review ESLint warnings
  • Verify build process
  • Check dependency issues

CD Failures ​

  • Verify SSH credentials
  • Check server connectivity
  • Review deployment logs
  • Verify Docker setup on server

Troubleshooting ​

Common Issues ​

Application Won't Start ​

Symptoms: Container fails to start or crashes immediately

Solutions:

  1. Check Docker logs: docker compose logs lager-guru
  2. Verify environment variables in .env
  3. Check port availability: netstat -tulpn | grep 80
  4. Verify Docker daemon: docker ps

Database Connection Errors ​

Symptoms: "Failed to connect to Supabase" or authentication errors

Solutions:

  1. Verify VITE_SUPABASE_URL and VITE_SUPABASE_PUBLISHABLE_KEY in .env
  2. Check Supabase project status
  3. Verify network connectivity
  4. Check RLS policies allow access

Real-time Updates Not Working ​

Symptoms: Changes don't appear without refresh

Solutions:

  1. Check Supabase Realtime is enabled
  2. Verify WebSocket connection in browser console
  3. Check RLS policies allow SELECT
  4. Verify subscription channels are correct

Barcode Scanner Not Working ​

Symptoms: Camera doesn't open or scanning fails

Solutions:

  1. Verify HTTPS is enabled (required for camera access)
  2. Check browser permissions for camera
  3. Test on different device/browser
  4. Check console for errors

GPS Tracking Not Working ​

Symptoms: Driver locations not updating

Solutions:

  1. Verify location permissions granted
  2. Check HTTPS is enabled
  3. Verify driver_locations table exists
  4. Check RLS policies for driver_locations

Build Failures ​

Symptoms: npm run build fails

Solutions:

  1. Clear node_modules: rm -rf node_modules && npm install
  2. Check TypeScript errors: npx tsc --noEmit
  3. Verify all dependencies installed
  4. Check for syntax errors

Performance Issues ​

Symptoms: Slow page loads or laggy UI

Solutions:

  1. Check network tab for slow requests
  2. Verify database queries are optimized
  3. Check for memory leaks
  4. Review RLS policy performance
  5. Enable service worker caching

Error Messages ​

"useAuth must be used within an AuthProvider" ​

Cause: Component using useAuth outside of AuthProvider

Solution: Wrap component tree with AuthProvider

"Row-level security policy violation" ​

Cause: RLS policy blocking access

Solution:

  1. Check user role
  2. Verify RLS policy conditions
  3. Check table permissions

"Failed to fetch" ​

Cause: Network error or CORS issue

Solution:

  1. Check network connectivity
  2. Verify Supabase URL is correct
  3. Check CORS settings in Supabase
  4. Verify API endpoint exists

Debugging Tips ​

Enable Debug Logging ​

Add to browser console:

javascript
localStorage.setItem('debug', 'true')

Check Supabase Connection ​

javascript
import { supabase } from '@/integrations/supabase/client'
const { data, error } = await supabase.from('shipments').select('*').limit(1)
console.log('Connection test:', { data, error })

Monitor Realtime Subscriptions ​

javascript
const channel = supabase.channel('test')
  .on('postgres_changes', { event: '*', schema: 'public', table: 'shipments' }, 
    (payload) => console.log('Realtime event:', payload)
  )
  .subscribe()

Getting Help ​

Check Logs ​

Docker logs:

bash
docker compose logs -f lager-guru

Nginx logs:

bash
sudo tail -f /var/log/nginx/error.log

Browser console: Open DevTools (F12)

Resources ​

Changelog ​

[Unreleased] ​

Added ​

  • Documentation site deployment preparation
  • Standalone VitePress documentation build

Changed ​

  • Documentation structure reorganized for standalone deployment

[1.0.0] - 2025-01-XX ​

Added ​

  • Initial release of Lager Guru WMS
  • Multi-tenant architecture with Row-Level Security
  • Enterprise SSO support (OIDC/SAML)
  • Inventory & Stock Management
  • Pick & Pack module
  • Warehouse Floor Plan visualization
  • Slotting Optimization AI
  • Maintenance Module
  • Safety & Compliance tracking
  • Equipment Tracking (QR/RFID)
  • Auto Assignment Engine
  • Routing Engine with 3D coordinates
  • Real-time analytics and KPIs
  • PWA support with offline capabilities

For detailed feature documentation, see the Getting Started Guide.

Resources ​

Documentation ​

Support ​

For issues and questions:

Contributing ​

When adding new features or components:

  1. Add JSDoc comments to your TypeScript/React code
  2. Update relevant documentation in the docs/ folder
  3. Run documentation generation: npm run docs:generate
  4. Preview changes: npm run docs:dev

Last updated: 2025-12-01

Copyright © 2025 HashMatrix

Released under Commercial License

Released under Commercial License

Copyright © 2025 HashMatrix