almhtrf111312/hyperpos-companion

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.