# tajnyofficial/sklepxd architecture

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

- Interactive diagram: https://gitdiagram.com/tajnyofficial/sklepxd
- Repository: https://github.com/tajnyofficial/sklepxd

## Overview

1. **Overall shape**
   - This is a **React + Vite** front-end repository for a retail/operations system called **sklepXD**.
   - The app is not a single UI: it is organized as a **multi-surface product** with separate experiences for **main back office**, **POS**, **kiosk**, and **mobile**.

2. **Entry points and deployment boundaries**
   - There is a primary app entry at `src/main.jsx` and also separate app entrypoints under `src/apps/`:
     - `src/apps/pos/main.jsx`
     - `src/apps/kiosk/main.jsx`
     - `src/apps/mobile/main.jsx`
   - Each of those has its own `index.html`, which means the repo supports **multiple independently served front-end entrypoints** rather than just a single routed SPA.
   - `vite.config.js` and `vercel.json` suggest Vite builds with deployment targeting Vercel.

3. **User-facing surfaces**
   - The `src/pages/` tree is organized by business domain:
     - **Dashboard / login**
     - **Admin**: roles, security, store settings, audit log, additional settings
     - **Communication**: announcements, tasks
     - **Deliveries**: suppliers, delivery schedule, deliveries
     - **Documents**
     - **Finance**: analytics, cash report, expenses, invoices, payments
     - **HR**: employees, absences, schedule, time tracking
     - **Inventory / warehouse / returns**
     - **POS**
     - **Kiosk**
     - **Mobile**
   - This indicates the architecture is centered around **operational workflows** rather than a generic CRUD app.

4. **Shared application state**
   - `src/contexts/AuthContext.jsx` likely owns authentication/session state and user identity.
   - `src/contexts/StoreContext.jsx` likely provides current store/location context used across pages and sub-apps.
   - These contexts are the main cross-cutting boundary between the UI and backend-driven business data.

5. **Backend integration**
   - `src/lib/supabase.js` is the central backend client, so the app uses **Supabase** as its data/auth platform.
   - The `supabase/` folder contains `migration.sql` and `rls_policies.sql`, showing that the backend model and **row-level security** are part of the repo’s architecture, not just external configuration.
   - This implies the front end relies on Supabase for at least data persistence, auth, and access control enforcement.

6. **Authorization model**
   - `src/utils/rbac.js` indicates **role-based access control** is implemented in the client, likely aligned with Supabase auth/claims or app-managed roles.
   - The presence of admin pages for roles and security suggests the app has a distinct **permission boundary** between operational users and administrators.

7. **Domain-specific components**
   - `src/components/BarcodeScanner/BarcodeScanner.jsx` and `src/hooks/useBarcodeScannerInput.js` show barcode input is a first-class workflow, especially relevant for inventory, POS, kiosk, and mobile scanning.
   - `src/components/Invoice/*` plus `src/utils/invoiceUtils.js` indicate invoice rendering/export is a dedicated subsystem, likely used in finance and document workflows.
   - `src/components/Modal.jsx` is a shared UI primitive used across many pages.

8. **Mobile, kiosk, and POS specialization**
   - The separate `src/apps/*` entrypoints and matching pages under `src/pages/pos`, `src/pages/kiosk`, and `src/pages/mobile` indicate each surface has its own UX and navigation model.
   - POS appears to focus on transaction flow and cash drawer management.
   - Mobile emphasizes scanning and stock/inventory actions.
   - Kiosk is likely a constrained interaction surface for self-service or lightweight task execution.

9. **Operational data domains**
   - The page structure suggests the system spans several tightly related domains:
     - **Inventory / warehouse** for stock, locations, transfers, alerts, product catalog
     - **Finance** for cash, expenses, invoices, payments, analytics
     - **HR** for workforce scheduling and attendance
     - **Deliveries / suppliers** for procurement and inbound logistics
     - **Returns** for reverse logistics
   - These domains likely share store context, auth, and common data access patterns through Supabase.

10. **UI composition and utility layer**
   - `src/components`, `src/hooks`, and `src/utils` form the shared application layer used by all surfaces.
   - `src/utils/helpers.js` likely contains generic formatting/transform helpers.
   - `src/index.css` and `src/App.css` imply a centralized styling baseline, while page and component files provide feature-specific UI.

11. **Top-level app structure**
   - `src/App.jsx` and `src/pages/DashboardPage.jsx` suggest the main back-office app uses a dashboard shell with feature pages mounted inside it.
   - `src/pages/LoginPage.jsx` is the likely authentication boundary before access to the rest of the system.
   - `src/main.jsx` is the root wiring point for providers, routing, and bootstrapping.

12. **Build/test/support tooling**
   - `eslint.config.js` and `add_jsdoc.cjs` show code quality and documentation tooling.
   - `scratch_test_supabase.js` suggests a local script for validating backend connectivity or Supabase behavior.
   - The repository is JavaScript-based rather than TypeScript, so the architecture relies more on conventions, folder boundaries, and Supabase policies than on compile-time types.

13. **What to capture in an architecture diagram**
   - Show **multiple front-end entrypoints** feeding into shared components/contexts/utils.
   - Show **Supabase** as the central backend for auth/data with **RLS** as an important enforcement boundary.
   - Show **role-based access control** gating page groups.
   - Show domain clusters around **inventory/warehouse**, **POS**, **mobile scanning**, **kiosk**, **finance**, **HR**, **deliveries**, and **admin**.
   - Show barcode scanning and invoicing as shared cross-domain services rather than isolated pages.

14. **Key architectural takeaway**
   - This repo is best understood as a **multi-channel retail operations front end** with a shared application core, several specialized runtime entrypoints, and Supabase-backed persistence plus security rules.

Main entry points: [`src/components/BarcodeScanner/BarcodeScanner.jsx`](https://github.com/tajnyofficial/sklepxd/blob/main/src/components/BarcodeScanner/BarcodeScanner.jsx) (Barcode scanner), [`vite.config.js`](https://github.com/tajnyofficial/sklepxd/blob/main/vite.config.js) (Vite build), [`src/main.jsx`](https://github.com/tajnyofficial/sklepxd/blob/main/src/main.jsx) (Main app), [`src/lib/supabase.js`](https://github.com/tajnyofficial/sklepxd/blob/main/src/lib/supabase.js) (Supabase client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Front-end surfaces"]
  node_main_entry["Main app<br/>entrypoint<br/>[main.jsx]"]
  node_app_shell["App shell<br/>[App.jsx]"]
  node_pos_entry["POS app<br/>entrypoint<br/>[main.jsx]"]
  node_kiosk_entry["Kiosk app<br/>entrypoint<br/>[main.jsx]"]
  node_mobile_entry["Mobile app<br/>entrypoint<br/>[main.jsx]"]
end

subgraph group_shared["Shared core"]
  node_auth_ctx["Auth context<br/>session state<br/>[AuthContext.jsx]"]
  node_store_ctx["Store context<br/>location state<br/>[StoreContext.jsx]"]
  node_rbac{{"RBAC<br/>authorization<br/>[rbac.js]"}}
  node_scanner["Barcode scanner<br/>input component<br/>[BarcodeScanner.jsx]"]
  node_scanner_hook["Scan hook<br/>input hook"]
  node_invoice["Invoices<br/>document subsystem"]
  node_modal["Modal<br/>ui primitive<br/>[Modal.jsx]"]
end

subgraph group_domains["Business domains"]
  node_dashboard["Dashboard<br/>back-office<br/>[DashboardPage.jsx]"]
  node_login["Login<br/>auth page<br/>[LoginPage.jsx]"]
  node_inventory["Inventory<br/>domain area<br/>[InventoryPage.jsx]"]
  node_warehouse["Warehouse<br/>domain area"]
  node_pos["POS<br/>transaction flow<br/>[POSPage.jsx]"]
  node_mobile["Mobile<br/>scanner workflow<br/>[MobileScanPage.jsx]"]
  node_kiosk["Kiosk<br/>self-service<br/>[KioskPage.jsx]"]
  node_finance["Finance<br/>domain area<br/>[AnalyticsPage.jsx]"]
  node_hr["HR<br/>domain area<br/>[EmployeesPage.jsx]"]
  node_deliveries["Deliveries<br/>domain area<br/>[DeliveriesPage.jsx]"]
  node_admin["Admin<br/>control plane<br/>[RolesPage.jsx]"]
  node_communication["Communication<br/>workflow area"]
  node_documents["Documents<br/>domain area<br/>[DocumentsPage.jsx]"]
  node_returns["Returns<br/>reverse logistics<br/>[ReturnsPage.jsx]"]
end

subgraph group_backend["Backend platform"]
  node_supabase_client[("Supabase client<br/>data/auth client<br/>[supabase.js]")]
  node_rls["RLS policies<br/>security rules<br/>[rls_policies.sql]"]
  node_schema["DB schema<br/>migration<br/>[migration.sql]"]
end

subgraph group_tooling["Tooling"]
  node_build["Vite build<br/>build config<br/>[vite.config.js]"]
  node_deploy["Vercel config<br/>deploy config<br/>[vercel.json]"]
end

node_main_entry -->|"boots"| node_app_shell
node_app_shell -->|"shows"| node_dashboard
node_app_shell -->|"guards"| node_login
node_main_entry -->|"provides"| node_auth_ctx
node_main_entry -->|"provides"| node_store_ctx
node_auth_ctx -->|"auth"| node_supabase_client
node_store_ctx -->|"data"| node_supabase_client
node_supabase_client -->|"uses"| node_schema
node_supabase_client -->|"enforced by"| node_rls
node_rbac -->|"controls"| node_admin
node_rbac -->|"controls"| node_finance
node_scanner_hook -->|"drives"| node_scanner
node_scanner -->|"supports"| node_inventory
node_scanner -->|"supports"| node_warehouse
node_scanner -->|"supports"| node_pos
node_scanner -->|"supports"| node_mobile
node_invoice -->|"supports"| node_finance
node_invoice -->|"supports"| node_documents
node_modal -.->|"shared UI"| node_dashboard
node_pos_entry -->|"renders"| node_pos
node_kiosk_entry -->|"renders"| node_kiosk
node_mobile_entry -->|"renders"| node_mobile
node_build -->|"builds"| node_main_entry
node_build -->|"builds"| node_pos_entry
node_build -->|"builds"| node_kiosk_entry
node_build -->|"builds"| node_mobile_entry
node_deploy -.->|"deploys"| node_build

click node_main_entry "https://github.com/tajnyofficial/sklepxd/blob/main/src/main.jsx"
click node_app_shell "https://github.com/tajnyofficial/sklepxd/blob/main/src/App.jsx"
click node_dashboard "https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/DashboardPage.jsx"
click node_login "https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/LoginPage.jsx"
click node_pos_entry "https://github.com/tajnyofficial/sklepxd/blob/main/src/apps/pos/main.jsx"
click node_kiosk_entry "https://github.com/tajnyofficial/sklepxd/blob/main/src/apps/kiosk/main.jsx"
click node_mobile_entry "https://github.com/tajnyofficial/sklepxd/blob/main/src/apps/mobile/main.jsx"
click node_auth_ctx "https://github.com/tajnyofficial/sklepxd/blob/main/src/contexts/AuthContext.jsx"
click node_store_ctx "https://github.com/tajnyofficial/sklepxd/blob/main/src/contexts/StoreContext.jsx"
click node_supabase_client "https://github.com/tajnyofficial/sklepxd/blob/main/src/lib/supabase.js"
click node_rls "https://github.com/tajnyofficial/sklepxd/blob/main/supabase/rls_policies.sql"
click node_schema "https://github.com/tajnyofficial/sklepxd/blob/main/supabase/migration.sql"
click node_rbac "https://github.com/tajnyofficial/sklepxd/blob/main/src/utils/rbac.js"
click node_scanner "https://github.com/tajnyofficial/sklepxd/blob/main/src/components/BarcodeScanner/BarcodeScanner.jsx"
click node_scanner_hook "https://github.com/tajnyofficial/sklepxd/blob/main/src/hooks/useBarcodeScannerInput.js"
click node_invoice "https://github.com/tajnyofficial/sklepxd/blob/main/src/components/Invoice/InvoiceDocument.jsx"
click node_modal "https://github.com/tajnyofficial/sklepxd/blob/main/src/components/Modal.jsx"
click node_inventory "https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/inventory/InventoryPage.jsx"
click node_warehouse "https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/warehouse/StockOverviewPage.jsx"
click node_pos "https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/pos/POSPage.jsx"
click node_mobile "https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/mobile/MobileScanPage.jsx"
click node_kiosk "https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/kiosk/KioskPage.jsx"
click node_finance "https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/finance/AnalyticsPage.jsx"
click node_hr "https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/hr/EmployeesPage.jsx"
click node_deliveries "https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/deliveries/DeliveriesPage.jsx"
click node_admin "https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/admin/RolesPage.jsx"
click node_communication "https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/communication/AnnouncementsPage.jsx"
click node_documents "https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/documents/DocumentsPage.jsx"
click node_returns "https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/returns/ReturnsPage.jsx"
click node_build "https://github.com/tajnyofficial/sklepxd/blob/main/vite.config.js"
click node_deploy "https://github.com/tajnyofficial/sklepxd/blob/main/vercel.json"

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_main_entry,node_app_shell,node_pos_entry,node_kiosk_entry,node_mobile_entry toneBlue
class node_auth_ctx,node_store_ctx,node_rbac,node_scanner,node_scanner_hook,node_invoice,node_modal toneAmber
class node_dashboard,node_login,node_inventory,node_warehouse,node_pos,node_mobile,node_kiosk,node_finance,node_hr,node_deliveries,node_admin,node_communication,node_documents,node_returns toneMint
class node_supabase_client,node_rls,node_schema toneRose
class node_build,node_deploy toneIndigo
```

## Components

### Front-end surfaces

Multiple independently served React entrypoints and the shared app shell.

- [Main app](https://github.com/tajnyofficial/sklepxd/blob/main/src/main.jsx): entrypoint · Primary React bootstrapping point for the back-office experience. · `src/main.jsx`
- [App shell](https://github.com/tajnyofficial/sklepxd/blob/main/src/App.jsx): shell · Top-level app composition and routing for the main surface. · `src/App.jsx`
- [POS app](https://github.com/tajnyofficial/sklepxd/blob/main/src/apps/pos/main.jsx): entrypoint · Dedicated POS runtime entrypoint. · `src/apps/pos/main.jsx`
- [Kiosk app](https://github.com/tajnyofficial/sklepxd/blob/main/src/apps/kiosk/main.jsx): entrypoint · Dedicated kiosk runtime entrypoint. · `src/apps/kiosk/main.jsx`
- [Mobile app](https://github.com/tajnyofficial/sklepxd/blob/main/src/apps/mobile/main.jsx): entrypoint · Dedicated mobile runtime entrypoint. · `src/apps/mobile/main.jsx`

### Shared core

Cross-cutting UI, state, and integration layers reused by all surfaces.

- [Auth context](https://github.com/tajnyofficial/sklepxd/blob/main/src/contexts/AuthContext.jsx): session state · Owns session and identity state. · `src/contexts/AuthContext.jsx`
- [Store context](https://github.com/tajnyofficial/sklepxd/blob/main/src/contexts/StoreContext.jsx): location state · Provides current store/location context across the app. · `src/contexts/StoreContext.jsx`
- [RBAC](https://github.com/tajnyofficial/sklepxd/blob/main/src/utils/rbac.js): authorization · Client-side role and permission checks. · `src/utils/rbac.js`
- [Barcode scanner](https://github.com/tajnyofficial/sklepxd/blob/main/src/components/BarcodeScanner/BarcodeScanner.jsx): input component · Shared barcode scanning UI and input handling. · `src/components/BarcodeScanner/BarcodeScanner.jsx`
- [Scan hook](https://github.com/tajnyofficial/sklepxd/blob/main/src/hooks/useBarcodeScannerInput.js): input hook · Low-level barcode keyboard/input integration. · `src/hooks/useBarcodeScannerInput.js`
- [Invoices](https://github.com/tajnyofficial/sklepxd/blob/main/src/components/Invoice/InvoiceDocument.jsx): document subsystem · Invoice rendering and download workflow. · `src/components/Invoice/InvoiceDocument.jsx`
- [Modal](https://github.com/tajnyofficial/sklepxd/blob/main/src/components/Modal.jsx): ui primitive · Shared dialog primitive used throughout the UI. · `src/components/Modal.jsx`

### Business domains

Back office and specialized operational areas exposed through pages.

- [Dashboard](https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/DashboardPage.jsx): back-office · Main landing page and operational hub. · `src/pages/DashboardPage.jsx`
- [Login](https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/LoginPage.jsx): auth page · Authentication boundary before accessing the app. · `src/pages/LoginPage.jsx`
- [Inventory](https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/inventory/InventoryPage.jsx): domain area · Core inventory and stock management pages. · `src/pages/inventory/InventoryPage.jsx`
- [Warehouse](https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/warehouse/StockOverviewPage.jsx): domain area · Locations, catalog, alerts, transfers, and stock overview. · `src/pages/warehouse/StockOverviewPage.jsx`
- [POS](https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/pos/POSPage.jsx): transaction flow · Point-of-sale workflow and history. · `src/pages/pos/POSPage.jsx`
- [Mobile](https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/mobile/MobileScanPage.jsx): scanner workflow · Mobile inventory, scan, and stock actions. · `src/pages/mobile/MobileScanPage.jsx`
- [Kiosk](https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/kiosk/KioskPage.jsx): self-service · Constrained kiosk interaction surface. · `src/pages/kiosk/KioskPage.jsx`
- [Finance](https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/finance/AnalyticsPage.jsx): domain area · Analytics, cash, expenses, invoices, and payments. · `src/pages/finance/AnalyticsPage.jsx`
- [HR](https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/hr/EmployeesPage.jsx): domain area · Employees, absences, scheduling, and time tracking. · `src/pages/hr/EmployeesPage.jsx`
- [Deliveries](https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/deliveries/DeliveriesPage.jsx): domain area · Suppliers and inbound delivery operations. · `src/pages/deliveries/DeliveriesPage.jsx`
- [Admin](https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/admin/RolesPage.jsx): control plane · Roles, security, store settings, audit log, and extra settings. · `src/pages/admin/RolesPage.jsx`
- [Communication](https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/communication/AnnouncementsPage.jsx): workflow area · Announcements and task coordination. · `src/pages/communication/AnnouncementsPage.jsx`
- [Documents](https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/documents/DocumentsPage.jsx): domain area · Document management surface. · `src/pages/documents/DocumentsPage.jsx`
- [Returns](https://github.com/tajnyofficial/sklepxd/blob/main/src/pages/returns/ReturnsPage.jsx): reverse logistics · Returns handling and related workflows. · `src/pages/returns/ReturnsPage.jsx`

### Backend platform

Supabase client and schema/security assets that define persistence and access control.

- [Supabase client](https://github.com/tajnyofficial/sklepxd/blob/main/src/lib/supabase.js): data/auth client · Central client for authentication and data access. · `src/lib/supabase.js`
- [RLS policies](https://github.com/tajnyofficial/sklepxd/blob/main/supabase/rls_policies.sql): security rules · Row-level security enforcement for backend data access. · `supabase/rls_policies.sql`
- [DB schema](https://github.com/tajnyofficial/sklepxd/blob/main/supabase/migration.sql): migration · Database structure and migration definitions. · `supabase/migration.sql`

### Tooling

Build, lint, and support scripts.

- [Vite build](https://github.com/tajnyofficial/sklepxd/blob/main/vite.config.js): build config · Vite configuration and deployment targeting. · `vite.config.js`
- [Vercel config](https://github.com/tajnyofficial/sklepxd/blob/main/vercel.json): deploy config · Deployment settings for Vercel. · `vercel.json`

## Connections

- Main app → App shell: boots · The main entrypoint mounts the primary application shell.
- App shell → Dashboard: shows · The shell routes users into the dashboard experience.
- App shell → Login: guards · Authentication gate before entering the app.
- Main app → Auth context: provides · Bootstraps shared authentication state.
- Main app → Store context: provides · Bootstraps shared store context.
- Auth context → Supabase client: auth · Session state is backed by the Supabase client.
- Store context → Supabase client: data · Store-scoped data access goes through Supabase.
- Supabase client → DB schema: uses · Client operates against the repository-managed schema.
- Supabase client → RLS policies: enforced by · Access is constrained by row-level security policies.
- RBAC → Admin: controls · Role checks gate administrative capabilities.
- RBAC → Finance: controls · Permission checks gate sensitive finance functions.
- Scan hook → Barcode scanner: drives · Hook powers shared barcode input behavior.
- Barcode scanner → Inventory: supports · Scanning is central to inventory workflows.
- Barcode scanner → Warehouse: supports · Scanning supports warehouse operations.
- Barcode scanner → POS: supports · Scanning supports checkout and transaction flow.
- Barcode scanner → Mobile: supports · Mobile app emphasizes barcode-driven actions.
- Invoices → Finance: supports · Invoice generation is part of finance workflows.
- Invoices → Documents: supports · Invoices also feed document handling.
- Modal → Dashboard: shared UI · Shared dialog primitive used across pages.
- POS app → POS: renders · Dedicated POS runtime renders POS pages.
- Kiosk app → Kiosk: renders · Dedicated kiosk runtime renders kiosk pages.
- Mobile app → Mobile: renders · Dedicated mobile runtime renders mobile pages.
- Vite build → Main app: builds · Vite bundles the main front-end entry.
- Vite build → POS app: builds · Vite bundles the POS entrypoint.
- Vite build → Kiosk app: builds · Vite bundles the kiosk entrypoint.
- Vite build → Mobile app: builds · Vite bundles the mobile entrypoint.
- Vercel config → Vite build: deploys · Deployment config targets the Vite build output.
