# robiulislam08/pos-frontend architecture

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

- Interactive diagram: https://gitdiagram.com/robiulislam08/pos-frontend
- Repository: https://github.com/robiulislam08/pos-frontend

## Overview

1. This repo is primarily a React-based POS front end, organized as a feature-driven single-page application. The visible stack is Vite + React, with Tailwind for styling and a small set of UI primitives for toasts, tooltips, and shared form/table controls.

2. The application is split by business domain under `src/features`, which is the main architectural boundary. Major modules include auth, inventory, sales, purchase, expense, barcode, backups, settings, help, and several “masters” screens for customer/supplier/user/product administration.

3. Shared UI and layout concerns live outside the feature folders. `src/components/layout` contains the app shell pieces like `AppLayout`, `Header`, `Navbar`, and `MobileNav`, while `src/components/common` holds reusable building blocks such as `DataTable`, `FormField`, `PageTitle`, `SummaryBar`, and action button groups.

4. State and cross-cutting concerns are handled through React contexts. `AuthContext` governs session/login state, and `LanguageContext` drives internationalization. This makes authentication and locale selection app-wide concerns rather than feature-local ones.

5. Routing is centralized in `src/routes/Routes.jsx`, with navigation definitions separated into `src/config/nav.config.js`. That suggests a clear split between route composition, menu generation, and page implementation, which is useful for diagrams of user navigation flow.

6. The data access layer is explicitly separated from the UI. `src/services/*.service.js` contains domain-specific API clients for auth, products, sales, purchases, stock, suppliers, customers, expenses, credits, settings, barcodes, and user management. These services likely all wrap a shared HTTP client in `src/services/api.js`.

7. Above the services, domain hooks in `src/hooks` provide feature-friendly state management and side effects. Hooks like `useProducts`, `useSales`, `useStock`, `useSuppliers`, `useUsers`, and `useExpenses` act as the bridge between pages and the API layer, keeping component code focused on rendering and user interaction.

8. The main runtime data flow is: user action in a page → feature hook → service call → shared API client → backend API → hook state update → UI refresh. Error and success messaging are handled through toast utilities in `src/lib/toast-helpers.js` and the UI toast components.

9. Internationalization is a first-class subsystem. Translations live in `src/i18n/en.json` and `src/i18n/ar.json`, indicating bilingual support, likely with Arabic as a right-to-left use case that affects layout and text rendering.

10. The repo includes a backend-facing story, but the frontend is the core artifact. `backend-api-implementation/`, `server.js`, and the Windows start scripts suggest a companion Node-based local server or deployment wrapper, while `vercel.json` indicates the front end can also be deployed as a web app.

11. Operationally, the project includes build/test/tooling boundaries: Vite for bundling, Vitest for tests, ESLint/PostCSS/Tailwind for code and styling, and `public/robots.txt` plus `index.html` for web deployment. These are supporting layers around the main POS UI and API integration architecture.

12. For an architecture diagram, the most important nodes are: the app shell/layout, feature pages, shared contexts, domain hooks, service/API layer, and the external backend. The business flow centers on POS operations like sales, inventory movement, purchases, credits, and reporting, with auth and language as global controls.

Main entry points: [`src/routes/Routes.jsx`](https://github.com/robiulislam08/pos-frontend/blob/main/src/routes/Routes.jsx) (Routes), [`src/hooks/useProducts.js`](https://github.com/robiulislam08/pos-frontend/blob/main/src/hooks/useProducts.js) (Feature hooks), [`src/App.jsx`](https://github.com/robiulislam08/pos-frontend/blob/main/src/App.jsx) (App), [`src/services/product.service.js`](https://github.com/robiulislam08/pos-frontend/blob/main/src/services/product.service.js) (Domain services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI shell"]
  node_app["App<br/>react entry<br/>[App.jsx]"]
  node_layout["Layout<br/>shell<br/>[AppLayout.jsx]"]
  node_common["Common UI<br/>shared components<br/>[DataTable.jsx]"]
  node_toastui(("Toast UI<br/>feedback primitives<br/>[toaster.jsx]"))
end

subgraph group_state["Cross-cutting state"]
  node_authctx(("Auth context<br/>session state<br/>[AuthContext.jsx]"))
  node_langctx(("Language context<br/>i18n state"))
  node_hooks(("Feature hooks<br/>state adapters<br/>[useProducts.js]"))
  node_i18n["Translations<br/>locale files<br/>[en.json]"]
end

subgraph group_data["Data layer"]
  node_routes["Routes<br/>navigation<br/>[Routes.jsx]"]
  node_navcfg["Nav config<br/>menu map<br/>[nav.config.js]"]
  node_api[("API client<br/>http client<br/>[api.js]")]
  node_services[("Domain services<br/>api wrappers<br/>[product.service.js]")]
end

subgraph group_features["Business features"]
  node_auth["Auth<br/>feature<br/>[LoginPage.jsx]"]
  node_inventory["Inventory<br/>feature cluster<br/>[StockPage.jsx]"]
  node_sales["Sales<br/>feature cluster<br/>[SalesPage.jsx]"]
  node_purchase["Purchase<br/>feature cluster"]
  node_masters["Masters<br/>admin feature cluster"]
  node_settings["Settings<br/>feature<br/>[SettingsPage.jsx]"]
  node_backup["Backup<br/>feature<br/>[BackupPage.jsx]"]
  node_barcode["Barcode<br/>feature<br/>[BarcodePage.jsx]"]
  node_help["Help<br/>feature<br/>[HelpPage.jsx]"]
end

subgraph group_ops["Runtime & deploy"]
  node_ops["Server & deploy<br/>runtime<br/>[server.js]"]
end

node_app -->|"renders"| node_layout
node_app -->|"uses"| node_routes
node_app -->|"wraps"| node_authctx
node_app -->|"wraps"| node_langctx
node_layout -->|"uses"| node_common
node_layout -->|"renders nav"| node_navcfg
node_layout -->|"shows feedback"| node_toastui
node_routes -->|"routes to"| node_auth
node_routes -->|"routes to"| node_inventory
node_routes -->|"routes to"| node_sales
node_routes -->|"routes to"| node_purchase
node_routes -->|"routes to"| node_masters
node_routes -->|"routes to"| node_settings
node_routes -->|"routes to"| node_backup
node_routes -->|"routes to"| node_barcode
node_routes -->|"routes to"| node_help
node_routes -.->|"depends on"| node_services
node_hooks -->|"calls"| node_services
node_services -->|"wraps"| node_api
node_authctx -.->|"authenticates via"| node_services
node_langctx -.->|"loads"| node_i18n
node_inventory -->|"uses"| node_hooks
node_sales -->|"uses"| node_hooks
node_purchase -->|"uses"| node_hooks
node_masters -->|"uses"| node_hooks
node_settings -->|"uses"| node_hooks
node_backup -.->|"uses"| node_services
node_barcode -->|"uses"| node_hooks
node_ops -.->|"serves"| node_app
node_ops -.->|"hosts"| node_routes

click node_app "https://github.com/robiulislam08/pos-frontend/blob/main/src/App.jsx"
click node_layout "https://github.com/robiulislam08/pos-frontend/blob/main/src/components/layout/AppLayout.jsx"
click node_common "https://github.com/robiulislam08/pos-frontend/blob/main/src/components/common/DataTable.jsx"
click node_toastui "https://github.com/robiulislam08/pos-frontend/blob/main/src/components/ui/toaster.jsx"
click node_authctx "https://github.com/robiulislam08/pos-frontend/blob/main/src/contexts/AuthContext.jsx"
click node_langctx "https://github.com/robiulislam08/pos-frontend/blob/main/src/contexts/LanguageContext.jsx"
click node_hooks "https://github.com/robiulislam08/pos-frontend/blob/main/src/hooks/useProducts.js"
click node_routes "https://github.com/robiulislam08/pos-frontend/blob/main/src/routes/Routes.jsx"
click node_navcfg "https://github.com/robiulislam08/pos-frontend/blob/main/src/config/nav.config.js"
click node_api "https://github.com/robiulislam08/pos-frontend/blob/main/src/services/api.js"
click node_services "https://github.com/robiulislam08/pos-frontend/blob/main/src/services/product.service.js"
click node_auth "https://github.com/robiulislam08/pos-frontend/blob/main/src/features/auth/LoginPage.jsx"
click node_inventory "https://github.com/robiulislam08/pos-frontend/blob/main/src/features/inventory/StockPage.jsx"
click node_sales "https://github.com/robiulislam08/pos-frontend/blob/main/src/features/sales/SalesPage.jsx"
click node_purchase "https://github.com/robiulislam08/pos-frontend/blob/main/src/features/purchase/PurchaseInvoicePage.jsx"
click node_masters "https://github.com/robiulislam08/pos-frontend/blob/main/src/features/masters/AddCustomerPage.jsx"
click node_settings "https://github.com/robiulislam08/pos-frontend/blob/main/src/features/settings/SettingsPage.jsx"
click node_backup "https://github.com/robiulislam08/pos-frontend/blob/main/src/features/backup/BackupPage.jsx"
click node_barcode "https://github.com/robiulislam08/pos-frontend/blob/main/src/features/barcode/BarcodePage.jsx"
click node_ops "https://github.com/robiulislam08/pos-frontend/blob/main/server.js"
click node_i18n "https://github.com/robiulislam08/pos-frontend/blob/main/src/i18n/en.json"
click node_help "https://github.com/robiulislam08/pos-frontend/blob/main/src/features/help/HelpPage.jsx"

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_app,node_layout,node_common,node_toastui toneBlue
class node_authctx,node_langctx,node_hooks,node_i18n toneAmber
class node_routes,node_navcfg,node_api,node_services toneMint
class node_auth,node_inventory,node_sales,node_purchase,node_masters,node_settings,node_backup,node_barcode,node_help toneRose
class node_ops toneIndigo
```

## Components

### UI shell

App shell, shared components, and page composition.

- [App](https://github.com/robiulislam08/pos-frontend/blob/main/src/App.jsx): react entry · Main React application bootstrap and composition root. · `src/App.jsx`
- [Layout](https://github.com/robiulislam08/pos-frontend/blob/main/src/components/layout/AppLayout.jsx): shell · App shell with header, navbar, and mobile navigation. · `src/components/layout/AppLayout.jsx`
- [Common UI](https://github.com/robiulislam08/pos-frontend/blob/main/src/components/common/DataTable.jsx): shared components · Reusable page controls such as tables, forms, titles, and action buttons. · `src/components/common/DataTable.jsx`
- [Toast UI](https://github.com/robiulislam08/pos-frontend/blob/main/src/components/ui/toaster.jsx): feedback primitives · Toast and tooltip primitives used for transient UI feedback. · `src/components/ui/toaster.jsx`

### Cross-cutting state

Contexts and hooks that coordinate app-wide or feature-level state.

- [Auth context](https://github.com/robiulislam08/pos-frontend/blob/main/src/contexts/AuthContext.jsx): session state · Global login and session state for the app. · `src/contexts/AuthContext.jsx`
- [Language context](https://github.com/robiulislam08/pos-frontend/blob/main/src/contexts/LanguageContext.jsx): i18n state · App-wide locale and language switching state. · `src/contexts/LanguageContext.jsx`
- [Feature hooks](https://github.com/robiulislam08/pos-frontend/blob/main/src/hooks/useProducts.js): state adapters · Domain hooks that bridge pages to services and manage side effects. · `src/hooks/useProducts.js`
- [Translations](https://github.com/robiulislam08/pos-frontend/blob/main/src/i18n/en.json): locale files · Bilingual English and Arabic translation resources. · `src/i18n/en.json`

### Data layer

Routing, config, services, and backend integration.

- [Routes](https://github.com/robiulislam08/pos-frontend/blob/main/src/routes/Routes.jsx): navigation · Central route composition for the SPA. · `src/routes/Routes.jsx`
- [Nav config](https://github.com/robiulislam08/pos-frontend/blob/main/src/config/nav.config.js): menu map · Navigation definitions used to generate menus and route-aware UI. · `src/config/nav.config.js`
- [API client](https://github.com/robiulislam08/pos-frontend/blob/main/src/services/api.js): http client · Shared HTTP layer used by all domain services. · `src/services/api.js`
- [Domain services](https://github.com/robiulislam08/pos-frontend/blob/main/src/services/product.service.js): api wrappers · Service modules for auth, inventory, sales, purchases, credits, settings, and users. · `src/services/product.service.js`

### Business features

Domain pages organized by business area.

- [Auth](https://github.com/robiulislam08/pos-frontend/blob/main/src/features/auth/LoginPage.jsx): feature · Login and session entry point. · `src/features/auth/LoginPage.jsx`
- [Inventory](https://github.com/robiulislam08/pos-frontend/blob/main/src/features/inventory/StockPage.jsx): feature cluster · Product, stock, credit, and adjustment workflows. · `src/features/inventory/StockPage.jsx`
- [Sales](https://github.com/robiulislam08/pos-frontend/blob/main/src/features/sales/SalesPage.jsx): feature cluster · Sales entry, returns, and reporting. · `src/features/sales/SalesPage.jsx`
- [Purchase](https://github.com/robiulislam08/pos-frontend/blob/main/src/features/purchase/PurchaseInvoicePage.jsx): feature cluster · Purchase invoice entry and review. · `src/features/purchase/PurchaseInvoicePage.jsx`
- [Masters](https://github.com/robiulislam08/pos-frontend/blob/main/src/features/masters/AddCustomerPage.jsx): admin feature cluster · Customer, supplier, formulation, user, and product administration screens. · `src/features/masters/AddCustomerPage.jsx`
- [Settings](https://github.com/robiulislam08/pos-frontend/blob/main/src/features/settings/SettingsPage.jsx): feature · Application configuration and preferences. · `src/features/settings/SettingsPage.jsx`
- [Backup](https://github.com/robiulislam08/pos-frontend/blob/main/src/features/backup/BackupPage.jsx): feature · Backup and recovery workflow. · `src/features/backup/BackupPage.jsx`
- [Barcode](https://github.com/robiulislam08/pos-frontend/blob/main/src/features/barcode/BarcodePage.jsx): feature · Barcode generation and related workflows. · `src/features/barcode/BarcodePage.jsx`
- [Help](https://github.com/robiulislam08/pos-frontend/blob/main/src/features/help/HelpPage.jsx): feature · User help and guidance page. · `src/features/help/HelpPage.jsx`

### Runtime & deploy

Build, hosting, and companion server artifacts.

- [Server & deploy](https://github.com/robiulislam08/pos-frontend/blob/main/server.js): runtime · Companion local server, start scripts, and deployment config. · `server.js`

## Connections

- App → Layout: renders · The app composes the global shell around routed content.
- App → Routes: uses · The app mounts the route tree for page navigation.
- App → Auth context: wraps · Authentication state is provided app-wide.
- App → Language context: wraps · Language state is provided app-wide.
- Layout → Common UI: uses · Shell screens use shared page controls and UI building blocks.
- Layout → Nav config: renders nav · The layout reads navigation definitions for menus.
- Layout → Toast UI: shows feedback · Shell-level UI can surface toast notifications.
- Routes → Auth: routes to · Login is one of the routed entry points.
- Routes → Inventory: routes to · Inventory pages are exposed through the route tree.
- Routes → Sales: routes to · Sales pages are exposed through the route tree.
- Routes → Purchase: routes to · Purchase pages are exposed through the route tree.
- Routes → Masters: routes to · Administration screens are exposed through the route tree.
- Routes → Settings: routes to · Settings is a routed destination.
- Routes → Backup: routes to · Backup is a routed destination.
- Routes → Barcode: routes to · Barcode tools are exposed through routing.
- Routes → Help: routes to · Help is available as a routed page.
- Routes → Domain services: depends on · Route-backed pages rely on domain services for data operations.
- Feature hooks → Domain services: calls · Feature hooks encapsulate service calls and side effects.
- Domain services → API client: wraps · Each domain service delegates to the shared HTTP client.
- Auth context → Domain services: authenticates via · Session state is backed by auth-related service calls.
- Language context → Translations: loads · Language context selects translation resources.
- Inventory → Feature hooks: uses · Inventory pages consume domain hooks for products, stock, and credits.
- Sales → Feature hooks: uses · Sales pages consume sales and stock-related hooks.
- Purchase → Feature hooks: uses · Purchase pages consume purchase-related hooks.
- Masters → Feature hooks: uses · Master data screens consume customer, supplier, user, and formulation hooks.
- Settings → Feature hooks: uses · Settings uses a dedicated hook for persisted configuration.
- Backup → Domain services: uses · Backup flows operate against service-backed data operations.
- Barcode → Feature hooks: uses · Barcode workflows use barcode-related state and side effects.
- Server & deploy → App: serves · The companion runtime serves the frontend application.
- Server & deploy → Routes: hosts · Deployment serves the SPA routes.