Storeharmony Desktop ERP

Offline-first Java/Swing desktop ERP for African SMEs

Overview

Storeharmony Desktop is a full-featured offline-first ERP desktop application built in Java (Swing) for African small and medium businesses. It powers retail operations — inventory management, point-of-sale, accounting, HR, customer management, and cloud synchronization — all working without reliable internet connectivity.

Key Facts

Language: Java 1.8 (Swing GUI)
Codebase: 5,741 Java source files
JPA Entities: 466
Database: H2 (embedded) or MySQL — configurable
ORM: Hibernate 5.3.26
Build: Apache Ant
Entry Point: com.storeharmony.Init
Runtime: Java 8, 1024MB min heap
License: Licensed per store instance (cloud activation)
Company: DabarObjects Solutions Limited

Architecture

Storeharmony Desktop uses a Plugin + Chassis architecture pattern. The chassis (HAGenericApplicationViewComponent) is a reusable, entity-agnostic Swing panel providing a table view, search bar, action grid, paging, and context menus. Domain logic is injected via a plugin object implementing HarmonyApplicationPlugin.

The application is structured in a three-layer separation per module:

UI Layer (src/com/storeharmony/{module}/) — panels, forms, table models
Action Layer (src/com/storeharmony/menus/{module}/) — menu items, toolbar buttons
Operations Layer (src/com/storeharmony/operations/{module}/) — business logic, database access

Entities (src/com/storeharmony/entities/) are shared JPA-annotated POJOs used across all layers.

Startup Flow

Init.main() — entry point, checks for updates via self-extracting zip, parses CLI args
HarmonyStartupKernel — initializes application mode (BASIC/STANDARD/PLUS), UI context, database connection, license validation
HarmonyMainFrame — creates the main window with dynamic menu bar and module tab system
XmlMenuBarBuilder — loads menu XML definitions, resolves actions, builds the navigation tree

Modules

Storeharmony Desktop organizes its features into these primary modules:

📦 Inventory

Products, variants, stock levels, categories, barcodes, procurement, transfers, production, audit, supplier management. Batch-aware costing with complete traceability.

💰 Sales & POS

Point-of-Sale interface, invoices, customer orders, layaway/reservations, returns, payment methods (cash, card, mobile money, QR), cashback, gift cards, printing.

📊 Accounting

Double-entry journals, chart of accounts, bank accounts, income statements, balance sheets, financial ratios, fixed assets, depreciation, VAT, multi-currency.

👥 Customers & CRM

Customer profiles, credit management, loyalty clubs, appointments, surveys, promos, wallet system, SMS communication, customer analytics.

👤 HR

Staff management, roles and permissions, attendance, payroll, penalties, work logs, user authentication with role-based access control.

☁️ Cloud Sync

Offline-first sync to cloud, online store integration (WooCommerce, Shopify), SMS gateway, mobile web access, real-time notifications.

Plugin Architecture

Every feature module in Storeharmony is built as a plugin that plugs into a reusable chassis component. This is the central design pattern:

Menu Action → instantiates chassis + plugin → chassis.configurePlugin(plugin) → renders full table view with search, paging, context menus, action grid, and side panel.

Key interfaces:

HarmonyApplicationPlugin — domain logic contract (table model, query, actions, side panel)
HAGenericApplicationViewComponent — reusable entity-agnostic chassis
HeavyApplicationPanelLoaderAction — bridges menu system to plugin chassis
HarmonyWindowType — EMBED (tab), INNER, DIALOG, or FRAME
DataViewingComponent / DataCapturingComponent — panel lifecycle contracts

Technology Stack

Category	Technology
Language	Java 1.8
UI	Swing (custom themed panels)
ORM	Hibernate 5.3.26 (JPA 2.1)
Database	H2 1.4.182 (embedded) or MySQL
Reporting	JasperReports, JFreeChart 1.5.6
PDF	PDFBox 2.0.27
Printing	ESC/POS (thermal printers), barcode4j
Barcode/QR	ZXing (integrated in source)
HTTP/API	Jetty 9.4, OkHttp 3.5
JSON	Jackson 2.17.1, Gson 1.7.1
Bluetooth	Bluecove 2.1.0
Serial Port	RXTX 2.2, jSSC
Export	Apache POI (Excel), jExcel, jtidy (HTML)
Webcam	Webcam Capture 0.3.12
Build	Apache Ant
Auth	Role-based access, license-key activation

Repository Structure

StoreharmonyDesktop/
├── src/
│   ├── com/storeharmony/              # Application code
│   │   ├── Init.java                  # Entry point
│   │   ├── core/                      # Framework core (startup, UI context, security, i18n)
│   │   ├── desktop/                   # Desktop shell (main frame, menus, activation)
│   │   ├── inventory/                 # Inventory module UI
│   │   ├── sales/                     # Sales & POS module UI
│   │   ├── accounting/                # Accounting module UI
│   │   ├── customers/                 # Customer management UI
│   │   ├── hr/                        # Human resources UI
│   │   ├── operations/                # Business logic & database operations
│   │   ├── menus/                     # Menu actions (action classes)
│   │   ├── entities/                  # JPA entity POJOs (466 entities)
│   │   ├── devices/                   # Hardware integration (printers, bluetooth, QR)
│   │   ├── cloud/                     # Cloud sync & online store integration
│   │   ├── onlinestore/               # WooCommerce & Shopify connectors
│   │   ├── server/                    # Embedded Jetty server
│   │   ├── settings/                  # Settings & configuration
│   │   ├── reports/                   # Report engine
│   │   ├── systems/                   # System framework (dialogs, UI resources, plugins, schedules)
│   │   └── utils/                     # Utilities (AI, barcode, images, money, PDF, tax, vision)
│   ├── META-INF/                      # Hibernate config, persistence.xml
│   └── ...
├── lib/                               # 80+ dependency JARs
├── design/                            # Architecture & pattern documentation
├── docs/                              # User guides
├── build.xml                          # Ant build script
├── inventory.md                       # 793-line inventory domain reference
└── Storeharmony.bat                   # Windows launcher

Getting Started

Building from source:

git clone https://github.com/dosrd/StoreharmonyDesktop.git
cd StoreharmonyDesktop
ant compile   # Compiles to dist/
ant jar       # Packages to dist/Storeharmony.jar
ant run       # Compiles and launches

Requirements: JDK 1.8, Apache Ant. The build is Windows-oriented (hardcoded JDK path), but the source compiles on any platform by adjusting build.xml.

Database: H2 embedded by default (zero config). MySQL via configuration panel at first launch.

Working Tree: dashboard-upgrade

The repository has an active branch dashboard-upgrade that adds a complete home-tab dashboard with live KPIs, JFreeChart charts, and FlatLaf styling. This is the current development focus.

Branch: dashboard-upgrade (GitHub)
49 new classes in src/com/storeharmony/desktop/dashpack/
New deps: FlatLaf 3.7.1 (modern Windows LAF), JFreeChart 1.5.6
33 existing classes in src/com/storeharmony/desktop/dashboard/ (screens)

See the dedicated Dashboard & UI Framework page for the full component catalog, architectural docs, and how to add new dashboard widgets.