Inventory Manager

Multi-branch inventory management system with kit/bag tracking, item displacements, QR code generation, and hierarchical geographic containment.

Repository Architecture

• backend/ — Spring Boot 3 REST API with Java 21, PostgreSQL, Flyway, JWT Authentication, RBAC, and JaVers audit logging.
• desktop/ — Cross-platform desktop application built with Tauri v2, Svelte 5, and Vite.
• docs/ — Architecture documentation, data models, workflows, and testing guides.

---

Quick Start

1. PostgreSQL Database Setup

The backend requires PostgreSQL 16+. You can run it via Docker or install locally:

Option A: Docker (Recommended)

docker run --name inventory-db \
  -e POSTGRES_DB=inventory_manager_java \
  -e POSTGRES_USER=inventory_user \
  -e POSTGRES_PASSWORD=your_password \
  -p 5432:5432 \
  -d postgres:16

Option B: Local PostgreSQL

psql -U postgres
CREATE DATABASE inventory_manager_java;
CREATE USER inventory_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE inventory_manager_java TO inventory_user;

---

2. Backend API Setup

1. Navigate to backend:

   cd backend
   

2. Run in development mode:

   mvn spring-boot:run
   

3. Or run the packaged executable JAR:

   mvn clean package -DskipTests
   java -jar target/backend-*-exec.jar --DB_PASSWORD=your_password
   

Backend Configuration Methods

When running the .jar file, configuration can be provided via:

• Command-line flags: java -jar backend.jar --DB_PASSWORD=secret --PORT=4001
• Environment variables: DB_PASSWORD=secret java -jar backend.jar
• External properties/YAML: Place an application.properties or application.yml next to the JAR.

Default backend API URL: http://localhost:4000/api (production runs on port 4002, demo on 4003).

---

3. Desktop Application Setup

The desktop frontend is built with Tauri v2 + Svelte 5.

Prerequisites

• Node.js 20+ and npm
• Rust 1.78+ (via rustup)
• System dependencies:
  • Linux (Debian/Ubuntu): libwebkit2gtk-4.1-dev build-essential curl wget file libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev
  • Linux (Fedora/RHEL): webkit2gtk4.1-devel openssl-devel curl wget libappindicator-gtk3-devel librsvg2-devel
  • Windows: Microsoft Visual Studio C++ Build Tools & WebView2 Runtime

Development Mode

cd desktop

# Install dependencies
npm install

# Run frontend dev server in browser
npm run dev

# Run Tauri desktop app with hot reload
npm run tauri dev

Backend URL Configuration

The desktop client can connect to any remote or local backend instance:

1. In-App Settings: Navigate to the Settings tab in the application UI, specify the Backend API URL (e.g. http://192.168.1.21:4002/api), and click Test Connection / Save.
2. Build/Dev Environment Variable: Set VITE_API_URL=http://localhost:4000/api in desktop/.env or when launching.

---

Building Release Packages

Backend JAR

mvn clean package -DskipTests
# Output: backend/target/backend-<version>-exec.jar

Desktop Installers & Binaries

From the desktop/ directory:

npm run tauri build

The generated bundles will be located in desktop/src-tauri/target/release/bundle/:

• Linux:
  • Debian package: deb/inventory-manager-desktop_<version>_amd64.deb
  • AppImage: appimage/inventory-manager-desktop_<version>_amd64.AppImage
  • Standalone Binary: desktop/src-tauri/target/release/inventory-manager-desktop
• Windows:
  • NSIS Installer: nsis/Inventory Manager_<version>_x64-setup.exe
  • MSI Installer: msi/Inventory Manager_<version>_x64_en-US.msi
  • Standalone EXE: desktop/src-tauri/target/release/inventory-manager-desktop.exe

---

Testing & Quality Gates

Backend Tests

# Run unit and integration tests
cd backend && mvn test

Desktop Tests

cd desktop

# Unit and component tests (Vitest)
npm test

# End-to-end tests (Playwright)
npm run test:e2e

CI / PR Quality Gates

• Remote CI checks enforce successful compilation, backend unit/integration tests, and desktop Vitest suites.
• Pre-push hooks validate clean builds and unit tests before pushing to remote branches.

---

Documentation

Detailed architectural and operational documentation:

• Physical Hierarchy & Locations
• Bags & Displacements
• Item Request Workflows
• Testing Strategy & Test Plan
• Local Run & Packaging
• Migration Notes