# almhtrf111312/hyperpos-companion architecture

> Architecture diagram of the GitHub repository almhtrf111312/hyperpos-companion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/almhtrf111312/hyperpos-companion
- Repository: https://github.com/almhtrf111312/hyperpos-companion

## Overview

1. **Overall shape**
   - This is a cross-platform POS / inventory / accounting-style application built as a React + TypeScript front end, with native packaging for Android (Capacitor) and Windows desktop (Electron).
   - The repo also includes a Supabase backend for authentication, persistence, and serverless business actions.

2. **Presentation layer**
   - `src/pages/*` holds the route-level screens such as POS, Dashboard, Products, Purchases, Reports, Settings, Login, and admin-oriented pages like BossPanel.
   - `src/components/*` contains reusable UI and feature components, split into clear feature areas: auth, license, layout, POS, barcode/camera, dashboard, reports, settings, onboarding, and setup.
   - `src/components/ui/*` is the shared design-system layer, based on shadcn-style primitives and Tailwind.

3. **Application shell and navigation**
   - `src/App.tsx`, `src/main.tsx`, and `src/components/layout/MainLayout.tsx` define the top-level app shell, navigation, and page composition.
   - Layout concerns are centralized in sidebar, notification, sync, and network-status components, which suggests a persistent shell around many feature pages rather than isolated page apps.

4. **Domain/data layer**
   - The business data model is mostly implemented in `src/lib/*-store.ts` modules such as products, invoices, customers, debts, expenses, partners, cashbox, profits, and maintenance.
   - This points to a local domain-store approach where features read/write through dedicated store modules instead of accessing the backend directly from UI components.

5. **Offline-first persistence and synchronization**
   - The presence of `indexeddb-cache`, `safe-storage`, `secure-storage`, `transaction-lock`, `sync-queue`, `sync-history`, and `local-auto-backup` shows an explicit offline-capable client architecture.
   - `src/providers/CloudSyncProvider.tsx`, `src/hooks/use-cloud-sync.tsx`, and `src/hooks/use-realtime-sync.tsx` appear to coordinate local writes, queued outbound sync, and remote reconciliation.
   - The `src/lib/cloud/*` modules split sync by business entity, so cloud writes are organized by domain object rather than by generic CRUD.

6. **Backend and server-side boundary**
   - Supabase is the main backend boundary: `src/integrations/supabase/client.ts`, generated types, `supabase/migrations/*`, and `supabase/functions/*`.
   - The edge functions cover license and user administration, account creation, password changes, device login/reset, activation validation, trial start, and help assistant flows.
   - This means some business rules are enforced server-side, especially around access control, licensing, and user/device lifecycle.

7. **Authentication, roles, device binding, and licensing**
   - The app has a dedicated auth and security layer with `use-auth`, `use-user-role`, `use-device-binding`, `ProtectedRoute`, `RoleGuard`, and device-blocked screens.
   - Licensing is treated as a first-class subsystem: `LicenseGuard`, activation screens, trial banners, offline protection, and encrypted-data messaging imply the app can restrict features or lock access based on license state.
   - This is important for diagramming because auth/licensing sits between navigation and business pages, not as an afterthought.

8. **Native and hardware integrations**
   - Barcode scanning is abstracted behind multiple implementations: web scanning, offline scanning, and native ML Kit scanning.
   - Camera support is similarly split between inline web camera and native preview.
   - There are also native helpers for printing and sharing, which indicates the app relies on platform-specific capabilities for core workflows like POS checkout and document output.

9. **Reporting and document generation**
   - `src/components/reports/*` and `src/lib/reports/dataset-builder.ts` suggest reports are built from shared datasets and then rendered into different report views.
   - Export/output utilities include PDF, Excel, file download, print helpers, and localized font support, so reporting is not just screen-based; it feeds external documents and printable artifacts.

10. **Settings, administration, and maintenance**
   - `src/components/settings/*` and pages like Settings, Cash Shifts, Warehouses, and Help show the app includes operational administration, not just transactional sales.
   - Backup, archive, reset, diagnostics, themes, language, profile, and license management are all centralized in the settings area, which is likely where system-level workflows are surfaced.

11. **Platform packaging**
   - Android packaging lives under `android/` with Capacitor integration, while Electron packaging lives under `electron/` with its own main process and error page.
   - The repo also includes PWA-related assets like `public/offline.html`, which suggests a third delivery mode in the browser.
   - This makes the architecture “single web codebase, multiple runtime shells.”

12. **Build and release pipeline**
   - GitHub Actions workflows build APKs and Windows artifacts.
   - Versioning and release files (`version.json`, `version.txt`, version bump scripts) imply a managed release process across app shells and backend-compatible clients.
   - The repo therefore has both application architecture and packaging/release architecture that are worth showing separately in a diagram.

Main entry points: [`src/App.tsx`](https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/App.tsx) (App Root), [`src/lib/products-store.ts`](https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/lib/products-store.ts) (Domain Stores), [`src/components/layout/MainLayout.tsx`](https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/components/layout/MainLayout.tsx) (Main Layout), [`src/main.tsx`](https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/main.tsx) (App Entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_app["App Shell & UI"]
  node_n_app_entry(("App Entry<br/>react entry<br/>[main.tsx]"))
  node_n_app_root["App Root<br/>router shell<br/>[App.tsx]"]
  node_n_main_layout["Main Layout<br/>navigation shell<br/>[MainLayout.tsx]"]
  node_n_pages["Pages<br/>route screens<br/>[POS.tsx]"]
  node_n_auth_ui["Auth UI<br/>access control UI<br/>[ProtectedRoute.tsx]"]
  node_n_license_ui["License UI<br/>license gating<br/>[LicenseGuard.tsx]"]
  node_n_pos_ui["POS UI<br/>checkout UI<br/>[CartPanel.tsx]"]
  node_n_report_ui["Reports UI<br/>report views<br/>[ReportShell.tsx]"]
  node_n_settings_ui["Settings UI<br/>admin settings"]
  node_n_ui_kit["UI Kit<br/>design system<br/>[button.tsx]"]
end

subgraph group_grp_domain["Domain & Offline Data"]
  node_n_cloud_sync["Cloud Sync<br/>sync orchestration"]
  node_n_local_stores[("Domain Stores<br/>business stores<br/>[products-store.ts]")]
  node_n_offline_cache[("Offline Cache<br/>persistence layer<br/>[indexeddb-cache.ts]")]
  node_n_report_data["Report Data<br/>dataset builder<br/>[dataset-builder.ts]"]
end

subgraph group_grp_backend["Supabase Backend"]
  node_n_backend_client[("Supabase Client<br/>backend boundary<br/>[client.ts]")]
  node_n_backend_functions["Edge Functions<br/>serverless actions<br/>[index.ts]"]
  node_n_backend_db[("Migrations<br/>database schema")]
end

subgraph group_grp_platform["Platform Shells"]
  node_n_android["Android Shell<br/>capacitor app<br/>[MainActivity.java]"]
  node_n_electron["Electron Shell<br/>desktop app<br/>[main.js]"]
  node_n_pwa_assets["PWA Assets<br/>web fallback<br/>[offline.html]"]
end

subgraph group_grp_release["Build & Release"]
  node_n_ci_build["CI Build<br/>release pipeline<br/>[build-apk.yml]"]
  node_n_versioning["Versioning<br/>release metadata<br/>[bump-version.js]"]
end

node_n_app_entry -->|"mounts"| node_n_app_root
node_n_app_root -->|"wraps"| node_n_main_layout
node_n_app_root -->|"routes to"| node_n_pages
node_n_app_root -->|"guards"| node_n_auth_ui
node_n_app_root -->|"restricts"| node_n_license_ui
node_n_main_layout -->|"hosts"| node_n_pos_ui
node_n_main_layout -->|"hosts"| node_n_report_ui
node_n_main_layout -->|"hosts"| node_n_settings_ui
node_n_pos_ui -->|"reads/writes"| node_n_local_stores
node_n_pages -->|"uses"| node_n_local_stores
node_n_cloud_sync -->|"syncs"| node_n_local_stores
node_n_cloud_sync -->|"queues"| node_n_offline_cache
node_n_local_stores -->|"persists"| node_n_offline_cache
node_n_report_ui -->|"renders"| node_n_report_data
node_n_report_data -->|"aggregates"| node_n_local_stores
node_n_backend_client -->|"accesses"| node_n_backend_db
node_n_backend_client -->|"invokes"| node_n_backend_functions
node_n_auth_ui -->|"authenticates"| node_n_backend_client
node_n_license_ui -->|"validates"| node_n_backend_functions
node_n_android -->|"hosts"| node_n_app_entry
node_n_electron -->|"hosts"| node_n_app_entry
node_n_pwa_assets -->|"falls back to"| node_n_app_entry
node_n_ci_build -->|"builds"| node_n_android
node_n_ci_build -->|"builds"| node_n_electron
node_n_versioning -->|"feeds"| node_n_ci_build

click node_n_app_entry "https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/main.tsx"
click node_n_app_root "https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/App.tsx"
click node_n_main_layout "https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/components/layout/MainLayout.tsx"
click node_n_pages "https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/pages/POS.tsx"
click node_n_auth_ui "https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/components/auth/ProtectedRoute.tsx"
click node_n_license_ui "https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/components/license/LicenseGuard.tsx"
click node_n_pos_ui "https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/components/pos/CartPanel.tsx"
click node_n_report_ui "https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/components/reports/ReportShell.tsx"
click node_n_settings_ui "https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/components/settings/LicenseManagement.tsx"
click node_n_ui_kit "https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/components/ui/button.tsx"
click node_n_cloud_sync "https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/providers/CloudSyncProvider.tsx"
click node_n_local_stores "https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/lib/products-store.ts"
click node_n_offline_cache "https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/lib/indexeddb-cache.ts"
click node_n_report_data "https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/lib/reports/dataset-builder.ts"
click node_n_backend_client "https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/integrations/supabase/client.ts"
click node_n_backend_functions "https://github.com/almhtrf111312/hyperpos-companion/blob/main/supabase/functions/check-license/index.ts"
click node_n_backend_db "https://github.com/almhtrf111312/hyperpos-companion/blob/main/supabase/migrations/20260113225837_15aafe59-1e02-46fa-9124-b89c8de0425c.sql"
click node_n_android "https://github.com/almhtrf111312/hyperpos-companion/blob/main/android/app/src/main/java/com/flowpos/pro/MainActivity.java"
click node_n_electron "https://github.com/almhtrf111312/hyperpos-companion/blob/main/electron/main.js"
click node_n_pwa_assets "https://github.com/almhtrf111312/hyperpos-companion/blob/main/public/offline.html"
click node_n_ci_build "https://github.com/almhtrf111312/hyperpos-companion/blob/main/.github/workflows/build-apk.yml"
click node_n_versioning "https://github.com/almhtrf111312/hyperpos-companion/blob/main/scripts/bump-version.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_app_entry,node_n_app_root,node_n_main_layout,node_n_pages,node_n_auth_ui,node_n_license_ui,node_n_pos_ui,node_n_report_ui,node_n_settings_ui,node_n_ui_kit toneBlue
class node_n_cloud_sync,node_n_local_stores,node_n_offline_cache,node_n_report_data toneAmber
class node_n_backend_client,node_n_backend_functions,node_n_backend_db toneMint
class node_n_android,node_n_electron,node_n_pwa_assets toneRose
class node_n_ci_build,node_n_versioning toneIndigo
```

## Components

### App Shell & UI

Route screens, shared layout, and reusable presentation components.

- [App Entry](https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/main.tsx): react entry · Bootstraps the web app and global providers. · `src/main.tsx`
- [App Root](https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/App.tsx): router shell · Top-level routing and application composition. · `src/App.tsx`
- [Main Layout](https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/components/layout/MainLayout.tsx): navigation shell · Persistent sidebar, status, sync, and notification chrome. · `src/components/layout/MainLayout.tsx`
- [Pages](https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/pages/POS.tsx): route screens · Major screens for POS, dashboard, catalog, accounting, admin, and settings. · `src/pages/POS.tsx`
- [Auth UI](https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/components/auth/ProtectedRoute.tsx): access control UI · Login, signup, reset, route protection, role and device gating. · `src/components/auth/ProtectedRoute.tsx`
- [License UI](https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/components/license/LicenseGuard.tsx): license gating · Activation, trial, and encrypted-data access restrictions. · `src/components/license/LicenseGuard.tsx`
- [POS UI](https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/components/pos/CartPanel.tsx): checkout UI · Cart, scanning, product dialogs, and checkout helpers. · `src/components/pos/CartPanel.tsx`
- [Reports UI](https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/components/reports/ReportShell.tsx): report views · Report shell, filters, charts, and operational reports. · `src/components/reports/ReportShell.tsx`
- [Settings UI](https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/components/settings/LicenseManagement.tsx): admin settings · Profile, backup, theme, language, diagnostics, and license settings. · `src/components/settings/LicenseManagement.tsx`
- [UI Kit](https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/components/ui/button.tsx): design system · Shared shadcn-style primitives and app-level UI building blocks. · `src/components/ui/button.tsx`

### Domain & Offline Data

Local business stores, sync orchestration, and client persistence.

- [Cloud Sync](https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/providers/CloudSyncProvider.tsx): sync orchestration · Coordinates local writes, queued sync, and realtime reconciliation. · `src/providers/CloudSyncProvider.tsx`
- [Domain Stores](https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/lib/products-store.ts): business stores · Products, invoices, customers, debts, expenses, partners, cashbox, and related state stores. · `src/lib/products-store.ts`
- [Offline Cache](https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/lib/indexeddb-cache.ts): persistence layer · IndexedDB, secure storage, locks, queue/history, and local backup. · `src/lib/indexeddb-cache.ts`
- [Report Data](https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/lib/reports/dataset-builder.ts): dataset builder · Assembles reusable reporting datasets from the business model. · `src/lib/reports/dataset-builder.ts`

### Supabase Backend

Auth, database boundary, and edge functions for licensing and admin actions.

- [Supabase Client](https://github.com/almhtrf111312/hyperpos-companion/blob/main/src/integrations/supabase/client.ts): backend boundary · Frontend client and generated types for Supabase access. · `src/integrations/supabase/client.ts`
- [Edge Functions](https://github.com/almhtrf111312/hyperpos-companion/blob/main/supabase/functions/check-license/index.ts): serverless actions · License, user, device, and help workflows enforced server-side. · `supabase/functions/check-license/index.ts`
- [Migrations](https://github.com/almhtrf111312/hyperpos-companion/blob/main/supabase/migrations/20260113225837_15aafe59-1e02-46fa-9124-b89c8de0425c.sql): database schema · Supabase schema and data model migrations. · `supabase/migrations/20260113225837_15aafe59-1e02-46fa-9124-b89c8de0425c.sql`

### Platform Shells

Native packaging and desktop/mobile runtime wrappers.

- [Android Shell](https://github.com/almhtrf111312/hyperpos-companion/blob/main/android/app/src/main/java/com/flowpos/pro/MainActivity.java): capacitor app · Native Android wrapper and activity host. · `android/app/src/main/java/com/flowpos/pro/MainActivity.java`
- [Electron Shell](https://github.com/almhtrf111312/hyperpos-companion/blob/main/electron/main.js): desktop app · Desktop runtime main process and error page. · `electron/main.js`
- [PWA Assets](https://github.com/almhtrf111312/hyperpos-companion/blob/main/public/offline.html): web fallback · Offline page and browser delivery assets. · `public/offline.html`

### Build & Release

Automation and versioning for cross-platform delivery.

- [CI Build](https://github.com/almhtrf111312/hyperpos-companion/blob/main/.github/workflows/build-apk.yml): release pipeline · GitHub Actions workflows for APK and Windows artifacts. · `.github/workflows/build-apk.yml`
- [Versioning](https://github.com/almhtrf111312/hyperpos-companion/blob/main/scripts/bump-version.js): release metadata · Version files and bump script used across builds and shells. · `scripts/bump-version.js`

## Connections

- App Entry → App Root: mounts · Bootstraps routing and global app composition.
- App Root → Main Layout: wraps · Places major screens inside the persistent application shell.
- App Root → Pages: routes to · Route-level pages are the main screen layer.
- App Root → Auth UI: guards · Authentication and role/device access control protect routes.
- App Root → License UI: restricts · License state can block or gate access to features.
- Main Layout → POS UI: hosts · POS workflow lives inside the shared shell.
- Main Layout → Reports UI: hosts · Reporting screens use the common layout and chrome.
- Main Layout → Settings UI: hosts · Operational admin screens are surfaced in settings.
- POS UI → Domain Stores: reads/writes · Checkout and product workflows operate through domain stores.
- Pages → Domain Stores: uses · Business pages bind to the local store layer instead of direct backend CRUD.
- Cloud Sync → Domain Stores: syncs · Synchronizes local domain changes with the cloud boundary.
- Cloud Sync → Offline Cache: queues · Uses offline persistence, locks, and queue/history for resilient sync.
- Domain Stores → Offline Cache: persists · Stores read and write through local offline-capable storage.
- Reports UI → Report Data: renders · Report screens consume shared datasets.
- Report Data → Domain Stores: aggregates · Report datasets are derived from the business stores.
- Supabase Client → Migrations: accesses · Frontend client talks to the Supabase schema.
- Supabase Client → Edge Functions: invokes · Client calls edge functions for privileged server actions.
- Auth UI → Supabase Client: authenticates · Login and session flows depend on the backend client.
- License UI → Edge Functions: validates · License activation and checks are enforced by serverless actions.
- Android Shell → App Entry: hosts · Android wraps the same web app entry point.
- Electron Shell → App Entry: hosts · Electron desktop shell launches the shared web codebase.
- PWA Assets → App Entry: falls back to · Browser delivery includes offline-friendly assets.
- CI Build → Android Shell: builds · CI produces mobile artifacts for Android.
- CI Build → Electron Shell: builds · CI produces desktop artifacts for Windows/Electron.
- Versioning → CI Build: feeds · Version metadata and bump scripts support release automation.