This project follows a modular monolith architecture with support for web, desktop, and mobile platforms. It uses a shared package-based design to encourage reusability and maintainability.
Contains platform-specific frontends:
desktop/: Electron app (main process, preload script, HTML entry).mobile/: Cordova-based mobile app.web/: Web application (e.g., Admin Dashboard, sync UI).
All shared logic and features are organized as packages here.
Reusable UI components like buttons, inputs, toast notifications, and sync indicators.
Core application logic and utilities:
auth.ts: Authentication logic.store.ts: Shared state management.permissions.ts: Role-based access control.utils.ts: Common utility functions.eventBus.ts: Decoupled event-driven communication.networkMonitor.ts: Online/offline state handling.moduleLoader.ts: Dynamic module registration and version control.
Database abstraction layer for offline/online sync.
pouchdb/: Local database.postgresql/: Remote API interaction for cloud/server data sync.
Feature-based modules (loosely coupled).
sales/: Sales feature – page, logic, version, and changelog.inventory/: Inventory feature.purchases/: Purchase module.loyalty/: Customer loyalty system.reports/: Analytics and reporting views.sync/: Advanced sync tools and logic:syncManager.ts: Orchestrates full sync.dbSwitch.ts: Handles PouchDB ↔ PostgreSQL switching.backupRestore.ts: Backup and restore logic.autoUpdater.ts: Automatic update trigger for modules.syncQueue.ts: Manages queued sync jobs.pushUpdateHandler.ts: Real-time update listener.
Centralized app and module configuration files.
app.config.ts: App-wide environment and settings.sync.config.ts: Sync frequency, modes, and endpoints.roles.config.ts: User roles and permission mapping.routing.config.ts: Module-specific or dynamic routing maps.
Backend logic (e.g., API endpoints).
index.ts: Entry point for Express server./routes/: API route handlers for each major module (sales, auth, updates, etc.).
Custom CLI scripts for building, deploying, and maintaining the project.
build-apps.ts: Bundle all platforms.build-electron.ts: Build Electron app.build-cordova.ts: Build Cordova app.backup-dump.ts: Backup local DB.restore-data.ts: Restore from backup.
Project-wide tests.
/unit/: Unit tests for individual logic files./integration/: Integration tests (e.g., sync across modules)./e2e/: End-to-end flow testing.
Deployment and environment configuration.
docker-compose.yml: Service definitions for container orchestration.deploy.sh: Shell script for CI/CD automation.nginx.conf: Web server configuration for production.
.eslintrc.js: ESLint configuration.tsconfig.json: TypeScript config.README.md: Project documentation.package.json: Dependencies and npm scripts.
- The project is modular, loosely coupled, and monolithic, which enables scalability while maintaining simplicity.
project-root/
│
├── apps/ # Frontend entry points for multiple platforms
│ ├── desktop/ # Electron-based desktop app
│ │ ├── electron-main.ts # Electron main process
│ │ ├── preload.ts # Preload script for secure context bridging
│ │ └── index.html # Desktop app HTML shell
│ ├── mobile/ # Cordova-based mobile app
│ │ ├── cordova-config.xml # Cordova configuration file
│ │ └── index.html # Mobile app HTML shell
│ └── web/ # Web frontend
│ ├── AdminDashboard.tsx # Main admin panel UI
│ └── UpdateTrigger.tsx # Component to handle update notifications
│
├── packages/ # Reusable libraries and shared logic
│ ├── ui/ # Common UI components
│ │ ├── Button.tsx
│ │ ├── Input.tsx
│ │ ├── SyncStatus.tsx
│ │ └── Toast.tsx
│ ├── core/ # Core logic and utilities
│ │ ├── auth.ts
│ │ ├── store.ts
│ │ ├── permissions.ts
│ │ ├── utils.ts
│ │ ├── eventBus.ts
│ │ ├── networkMonitor.ts
│ │ └── moduleLoader.ts
│ ├── db/ # Database interfaces
│ │ ├── pouchdb/
│ │ │ └── index.ts # Local DB implementation (offline-first)
│ │ └── postgresql/
│ │ └── api.ts # API connector for server-side PostgreSQL
│ └── modules/ # Feature-based modular business logic
│ ├── sales/
│ │ ├── index.ts # Module registration + metadata
│ │ ├── SalesPage.tsx
│ │ ├── useSales.ts
│ │ ├── version.ts
│ │ └── changelog.md
│ ├── inventory/
│ │ ├── InventoryPage.tsx
│ │ └── useInventory.ts
│ ├── purchases/
│ │ ├── PurchasePage.tsx
│ │ └── usePurchase.ts
│ ├── loyalty/
│ │ ├── LoyaltyPage.tsx
│ │ └── useLoyalty.ts
│ ├── reports/
│ │ ├── ReportsPage.tsx
│ │ └── useReports.ts
│ └── sync/ # Sync engine and tools
│ ├── syncManager.ts
│ ├── dbSwitch.ts
│ ├── backupRestore.ts
│ ├── autoUpdater.ts
│ ├── syncQueue.ts
│ └── pushUpdateHandler.ts
│
├── config/ # App-wide config files
│ ├── app.config.ts
│ ├── sync.config.ts
│ ├── roles.config.ts
│ └── routing.config.ts
│
├── server/ # Backend API server (Express)
│ └── express-api/
│ ├── index.ts
│ └── routes/
│ ├── sales.ts
│ ├── inventory.ts
│ ├── reports.ts
│ ├── purchases.ts
│ ├── auth.ts
│ └── updates.ts
│
├── scripts/ # Developer tools and CLI utilities
│ ├── build-apps.ts
│ ├── build-electron.ts
│ ├── build-cordova.ts
│ ├── backup-dump.ts
│ └── restore-data.ts
│
├── test/ # All tests (unit, integration, e2e)
│ ├── unit/
│ │ ├── sales.test.ts
│ │ └── syncQueue.test.ts
│ ├── integration/
│ │ └── sync.test.ts
│ └── e2e/
│ └── end-to-end-flow.test.ts
│
├── devops/ # Deployment & infrastructure
│ ├── docker-compose.yml
│ ├── deploy.sh
│ └── nginx.conf
│
├── .eslintrc.js # Linting configuration
├── tsconfig.json # TypeScript configuration
├── README.md # Project documentation
└── package.json # Project metadata & dependencies