LogShip ERP — Technical Documentation

Comprehensive technical reference for the LogShip WMS/ERP web application frontend.

LogShip ERP is a full-featured, enterprise-grade Enterprise Resource Planning and Warehouse Management System (WMS) frontend, built with Nuxt 3 and Vue 3. It manages the full lifecycle of sales orders, procurement, inventory, fulfillment, manufacturing, accounting, and business operations across multiple organisations and tenants.

The backend is powered by iDempiere ERP, with auxiliary services provided by Laravel, Strapi CMS, PostgREST, and Elasticsearch. The frontend proxies all requests through Nuxt server routes, handling token refresh, error classification, and multi-backend orchestration transparently.

Key Statistics

Technology Stack

Core Framework

UI & Styling

Data Grids & Charts

Document Processing

Barcode, Scanning & OCR

Mobile & PWA

Backend & Database

Directory Structure

Configuration

nuxt.config.ts

The central configuration file defines all modules, CSS processing, runtime variables, and build options.

Runtime Configuration

Environment variables are mapped to runtimeConfig and accessed via useRuntimeConfig():

Data Flow Architecture

All client requests are proxied through Nuxt server routes. The frontend never communicates directly with external APIs. This architecture enables transparent token refresh, error handling, and multi-backend routing.

Request Lifecycle

Every server API endpoint follows a consistent try/catch pattern with automatic token refresh:

export default defineEventHandler(async (event) => {
  let data: any = {}
  try {
    // 1. First attempt with current token
    data = await handleFunc(event)
  } catch(err) {
    try {
      // 2. Token expired? Refresh and retry
      let authToken = await refreshTokenHelper(event)
      data = await handleFunc(event, authToken)
    } catch(error) {
      // 3. Still failing? Classify and handle error
      data = errorHandlingHelper(err, error)
      forceLogoutHelper(event, data)  // Only logouts on true auth failures
    }
  }
  return data
})

Server Middleware Pipeline

Two server middleware modules run on every request before reaching API routes:

Authentication Flow

Login Process

Session Cookies

Token Refresh Strategy

A two-tier refresh mechanism ensures session continuity:

Error Handling & Classification

The system uses intelligent error classification to distinguish between authentication failures (which require logout) and authorization failures (which do not). This logic exists on both frontend (useAuthError.ts) and backend (authErrorHelper.ts).

Pages & Routing

Nuxt's file-based routing generates 463 routes from 18 main modules. Most resources follow a standard CRUD pattern:

/[module]/[resource]/           → index.vue     (List/Grid view)
/[module]/[resource]/create     → create.vue    (Create form)
/[module]/[resource]/add        → add.vue       (Alternative create)
/[module]/[resource]/[id]       → [id]/view.vue (Read-only detail)
/[module]/[resource]/[id]/edit  → [id]/edit.vue (Edit form)
/[module]/[resource]/[id]/duplicate → [id]/duplicate.vue (Clone)
/[module]/[resource]/[id]/print → [id]/print.vue (Print/PDF)

Module Route Summary

Public Routes (No Authentication)

Layouts

Middleware

Components

Component Inventory by Domain

Key Root-Level Components

Data Display

Navigation

Modals & Dialogs

Inputs & Utilities

Component Patterns

All components use the Vue 3 Composition API with <script setup lang="ts">:

<script setup lang="ts">
interface Props {
  modelValue?: any
  options?: any[]
  placeholder?: string
}

interface Emits {
  (e: 'update:modelValue', value: any): void
  (e: 'change', value: any): void
}

const props = withDefaults(defineProps<Props>(), { ... })
const emit = defineEmits<Emits>()
</script>

Naming Convention for Domain Components

Composables

UI State Composables

Defined in composables/states.ts, these provide global reactive state without a store library:

Feature Composables

Menu Composables

Each ERP module has a dedicated menu composable that defines its sidebar navigation structure. Located in composables/ and composables/menu/:

Plugins

State Management

The application uses Nuxt 3's built-in useState() for all reactive state. There is no Pinia or Vuex store. This approach provides SSR-safe reactive state with automatic hydration.

// composables/states.ts
export const useSideBar = () => useState<boolean>('sideBar', () => false)
export const useTabs = () => useState<any[]>('tabs', () => [
  { link: '/', text: 'Home', active: true }
])
export const useActiveMenu = () => useState<string>('activeMenu', () => '')

State Categories

Server API Layer

The server/api/ directory contains 1167+ API route files that proxy requests to various backends. Routes follow Nuxt's file-based convention with HTTP method suffixes.

API Route Convention

server/api/[resource]/
├── index.get.ts              # GET    /api/[resource]       (List)
├── index.post.ts             # POST   /api/[resource]       (Create)
├── store.post.ts             # POST   /api/[resource]/store (Alternative create)
├── update.put.ts             # PUT    /api/[resource]       (Update)
├── [id]/index.get.ts         # GET    /api/[resource]/[id]  (Get single)
├── [id]/index.put.ts         # PUT    /api/[resource]/[id]  (Update single)
├── [id]/index.delete.ts      # DELETE /api/[resource]/[id]  (Delete)
└── [custom-action].post.ts   # POST   /api/[resource]/...   (Custom action)

Major API Modules

Server Utilities

Databases

External Integrations

ERP Modules

Sales Management

Full sales lifecycle management from order creation to fulfillment.

Materials & Inventory

Comprehensive inventory management with 93 pages covering products, stock, warehouses, and pricing.

Procurement

Purchase order lifecycle from requisition to vendor payment.

Other Modules

Real-time Features

Server-Sent Events (SSE)

The useOrderStream composable establishes an SSE connection to /api/orders/sales/stream for live order updates:

// Message types:
// - "connected"   → Stream established
// - "newOrders"   → New orders available (triggers notification)
// - "heartbeat"   → Keep-alive signal
// - "error"       → Stream error (triggers reconnect)

const { startStream, stopStream, updateFilters } = useOrderStream({
  orgId: organizationId,
  documentNo: filterDocNo,
  openOnly: true,
  onNewOrders: (orders) => notifyNewOrders(orders.length)
})

Polling Fallback

When SSE is unavailable, useOrderPolling provides a configurable polling interval (default 30 seconds) with duplicate detection.

Push Notifications

Web Push with VAPID authentication. Service worker receives push events and displays native notifications with action buttons (e.g., "View Orders"). Push subscriptions are stored in SQLite and automatically cleaned up after 90 days.

Mobile & PWA

Capacitor Integration

Mobile Features

• Orientation Lock: Portrait lock for phones (screen width < 600px), free rotation for tablets
• Touch Targets: Minimum 48px touch areas
• Landscape Warning: Overlay shown when phone is rotated
• Native Scanner: DataWedge integration for Zebra/Honeywell enterprise scanners
• App Updates: OTA update detection with APK download and install
• Dark Mode: Optimised for scanner usage

PWA Support

• Service Worker: Registered globally for offline support and push notifications
• Manifest: public/manifest.json with app icons and theme colour
• Install Prompt: usePWAInstall composable detects standalone mode and handles beforeinstallprompt

Mobile Pages

Barcode & QR Code Scanning

Browser-Based (Quagga2)

Native Scanner (Capacitor)

Listens for DataWedge broadcasts from enterprise-grade scanners (Zebra, Honeywell). Falls back to custom nativeScan events. Detects if running on native platform via Capacitor bridge.

OCR (Tesseract.js)

Optical Character Recognition for text extraction from images. Used for document processing and label reading.

Document Processing

Shipping Integration

DHL Parcel

SendCloud

Extensible Architecture

Shipping processors are configurable through /materials/shipping-processors and /materials/shipping-processor-configurations, allowing new carriers to be added without code changes.

Internationalisation

The application supports 194+ languages with translation files in /assets/langs/.

Push Notifications

Architecture

Build & Deployment

Scripts

Build Configuration

Environment Configuration

Three environment files support different deployment targets:

Key Environment Variables

Code Patterns & Conventions

Page Pattern

// Standard page template
<script setup lang="ts">
definePageMeta({
  layout: 'app',
  middleware: ['auth']
})

const headers = useRequestHeaders(['cookie'])
const { data } = await useFetch('/api/resource', { headers })
</script>

API Endpoint Pattern

// Standard server API with token refresh
export default defineEventHandler(async (event) => {
  const handleFunc = async (event: any, token?: string) => {
    const authToken = token || getTokenHelper(event)
    return await fetchHelper(event, 'endpoint', 'GET', authToken, null)
  }

  let data: any = {}
  try {
    data = await handleFunc(event)
  } catch(err) {
    try {
      let authToken = await refreshTokenHelper(event)
      data = await handleFunc(event, authToken)
    } catch(error) {
      data = errorHandlingHelper(err, error)
      forceLogoutHelper(event, data)
    }
  }
  return data
})

Data Fetching Pattern (Client)

// Pattern 1: useFetch (SSR-compatible)
const { data } = await useFetch('/api/orders', {
  headers: useRequestHeaders(['cookie'])
})

// Pattern 2: Direct $fetch (client-side)
const loadData = async () => {
  const res = await $fetch('/api/orders?page=1&size=20', {
    headers: useRequestHeaders(['cookie'])
  })
  if (res?.records) items.value = res.records
}

iDempiere Data Model Pattern

// Entity references use ID + tableName format:
{
  AD_Org_ID:         { id: orgId, tableName: 'AD_Org' },
  C_BPartner_ID:     { id: partnerId, tableName: 'C_BPartner' },
  M_Warehouse_ID:    { id: warehouseId, tableName: 'M_Warehouse' },
  C_Order_ID:        { id: orderId, tableName: 'C_Order' },
  M_Product_ID:      { id: productId, tableName: 'M_Product' }
}

API Response Format

// Standard response from iDempiere
{
  "records": [
    { "id": 1, "name": "...", ... },
    { "id": 2, "name": "...", ... }
  ],
  "page-count": 5,
  "records-size": 100,
  "skip-records": 0,
  "row-count": 100
}