# 0xissam/business-flow-frontend architecture

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

- Interactive diagram: https://gitdiagram.com/0xissam/business-flow-frontend
- Repository: https://github.com/0xissam/business-flow-frontend

## Overview

This repository is a **Next.js frontend** with an **Electron desktop wrapper**. The architecture is centered on a React/Next app in `src/app`, with Electron entrypoints under `electron/` for packaging and desktop runtime.

1. **Application runtime**
   - The core UI runs as a **Next.js App Router** application (`src/app`).
   - The desktop distribution is handled by **Electron** (`electron/main.js`, `electron/preload.js`) and `electron-builder.yml`, which suggests this frontend can be shipped as a standalone desktop app rather than only a browser app.

2. **Route-level organization**
   - The app is split into route groups:
     - `src/app/(auth)` for authentication flows, currently a `login` page.
     - `src/app/(dashboard)` for the main business application.
   - This indicates a clear boundary between unauthenticated access and the authenticated operational area.

3. **Dashboard shell**
   - `src/app/(dashboard)/layout.tsx` is the shared shell for the business area.
   - The dashboard pages under this group cover the major business modules: `products`, `inventory`, `purchases`, `sales/pos`, `customers`, `suppliers`, `returns`, `expenses`, `reports`, `users`, `settings`, and more.
   - This structure implies the layout provides persistent navigation and shared chrome around module pages.

4. **Business modules as route pages**
   - Each domain area has its own page entrypoint, e.g.:
     - `products/page.tsx`
     - `inventory/page.tsx`
     - `pos/page.tsx`
     - `reports/page.tsx`
   - This is a page-per-module architecture, where each page likely composes shared UI components and calls the same app services layer rather than embedding business logic in the route tree.

5. **Shared UI component layer**
   - `src/components/ui` contains reusable primitives such as buttons, dialogs, tables, inputs, selects, badges, cards, and textareas.
   - `src/components/sidebar.tsx` is a navigation shell component, likely used by the dashboard layout.
   - `src/components/language-switcher.tsx` suggests the UI supports runtime language switching.
   - These components form the presentation boundary and are reused across multiple route pages.

6. **State and session boundary**
   - `src/hooks/useAuth.tsx` is the main custom hook for authentication state.
   - Its presence suggests login/session state is managed client-side and shared across the app, probably gating access to dashboard routes and exposing current user/session information.

7. **Service and integration layer**
   - `src/lib/api.ts` is the central API abstraction, likely the point where the frontend talks to a backend service.
   - `src/lib/receipt-print.ts` indicates a dedicated printing integration path, which is important for POS/register workflows and likely interacts with Electron or browser print capabilities.
   - `src/lib/utils.ts` contains shared helper logic used across the UI.

8. **Internationalization support**
   - `src/lib/i18n.tsx` and the language switcher indicate the app has a localized UI layer.
   - This is a cross-cutting concern that affects the shell, forms, tables, and business pages rather than a single feature.

9. **Provider composition**
   - `src/providers/index.tsx` is the application provider wrapper.
   - This is typically where global context providers are assembled, so it is an important boundary for app-wide concerns like auth, theme, localization, or data clients.

10. **App entrypoints and global styling**
   - `src/app/layout.tsx` is the root Next layout.
   - `src/app/page.tsx` is the top-level landing route.
   - `src/app/globals.css`, `tailwind.config.js`, and `postcss.config.js` show a Tailwind-based styling pipeline applied globally.

11. **Electron boundary**
   - The Electron files define the desktop runtime layer that wraps the web app.
   - `preload.js` is the bridge layer, which usually exposes safe desktop capabilities to the renderer while keeping direct Node access out of the UI.
   - This matters architecturally because features like printing or filesystem/device access may be routed through Electron rather than the browser.

12. **What is not in the repo**
   - There is no backend service implementation here, so the frontend likely depends on an external API or local service exposed through `src/lib/api.ts`.
   - The repository is therefore best diagrammed as a **desktop/web client** with a **shared UI and route structure**, plus **external backend/API dependencies**.

13. **Practical diagram boundaries**
   - A good architecture diagram should show:
     - Electron shell around the app
     - Next.js renderer/UI
     - Auth flow leading into dashboard shell
     - Shared UI/component layer beneath route pages
     - API/integration layer connecting to backend services
     - Printing and localization as cross-cutting services

In short, this is a **modular, route-driven business application frontend** with a **desktop Electron packaging layer**, a **shared dashboard shell**, and **domain-specific pages** for retail/operations workflows like POS, inventory, purchases, and reporting.

Main entry points: [`src/app/(dashboard)/layout.tsx`](https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/layout.tsx) (Dashboard shell), [`src/lib/api.ts`](https://github.com/0xissam/business-flow-frontend/blob/main/src/lib/api.ts) (API client), [`src/app/layout.tsx`](https://github.com/0xissam/business-flow-frontend/blob/main/src/app/layout.tsx) (Root layout), [`src/providers/index.tsx`](https://github.com/0xissam/business-flow-frontend/blob/main/src/providers/index.tsx) (Providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_electron["Electron"]
  node_node_electron_main["Main process<br/>electron-main<br/>[main.js]"]
  node_node_electron_preload["Preload bridge<br/>electron-preload<br/>[preload.js]"]
end

subgraph group_group_app["Next app"]
  node_node_root_layout["Root layout<br/>next-layout<br/>[layout.tsx]"]
  node_node_root_page["Landing page<br/>route-page<br/>[page.tsx]"]
  node_node_auth_login["Login<br/>auth-route<br/>[page.tsx]"]
  node_node_dashboard_layout["Dashboard shell<br/>dashboard-layout<br/>[layout.tsx]"]
  node_node_dashboard_home["Dashboard home<br/>module-page<br/>[page.tsx]"]
  node_node_products_page["Products<br/>module-page<br/>[page.tsx]"]
  node_node_inventory_page["Inventory<br/>module-page<br/>[page.tsx]"]
  node_node_purchases_page["Purchases<br/>module-page<br/>[page.tsx]"]
  node_node_pos_page["POS<br/>module-page<br/>[page.tsx]"]
  node_node_reports_page["Reports<br/>module-page<br/>[page.tsx]"]
  node_node_customers_page["Customers<br/>module-page<br/>[page.tsx]"]
  node_node_suppliers_page["Suppliers<br/>module-page<br/>[page.tsx]"]
  node_node_returns_page["Returns<br/>module-page<br/>[page.tsx]"]
  node_node_expenses_page["Expenses<br/>module-page<br/>[page.tsx]"]
  node_node_other_customers_page["Other customers<br/>module-page<br/>[page.tsx]"]
  node_node_categories_page["Categories<br/>module-page<br/>[page.tsx]"]
  node_node_users_page["Users<br/>admin-page<br/>[page.tsx]"]
  node_node_settings_page["Settings<br/>[page.tsx]"]
end

subgraph group_group_shared["Shared UI"]
  node_node_sidebar["Sidebar<br/>nav-shell<br/>[sidebar.tsx]"]
  node_node_language_switcher["Language switcher<br/>i18n-ui"]
  node_node_ui_primitives["UI primitives<br/>component-kit"]
  node_node_use_auth["Auth hook<br/>state-hook<br/>[useAuth.tsx]"]
  node_node_api["API client<br/>integration-client<br/>[api.ts]"]
  node_node_receipt_print["Receipt print<br/>printing-integration<br/>[receipt-print.ts]"]
  node_node_i18n["i18n<br/>locale-runtime<br/>[i18n.tsx]"]
  node_node_utils["Utils<br/>[utils.ts]"]
end

subgraph group_group_platform["Platform"]
  node_node_providers["Providers<br/>[index.tsx]"]
  node_node_globals_css["Global styles<br/>styling<br/>[globals.css]"]
end

node_node_electron_main -->|"loads bridge"| node_node_electron_preload
node_node_electron_main -->|"hosts UI"| node_node_root_layout
node_node_root_layout -->|"wraps with"| node_node_providers
node_node_root_layout -->|"imports styles"| node_node_globals_css
node_node_root_layout -->|"renders route"| node_node_root_page
node_node_root_layout -->|"routes to"| node_node_auth_login
node_node_root_layout -->|"routes to"| node_node_dashboard_layout
node_node_dashboard_layout -->|"uses"| node_node_sidebar
node_node_dashboard_layout -->|"guards with"| node_node_use_auth
node_node_dashboard_layout -->|"includes"| node_node_language_switcher
node_node_dashboard_layout -->|"contains"| node_node_dashboard_home
node_node_dashboard_layout -->|"contains"| node_node_products_page
node_node_dashboard_layout -->|"contains"| node_node_inventory_page
node_node_dashboard_layout -->|"contains"| node_node_purchases_page
node_node_dashboard_layout -->|"contains"| node_node_pos_page
node_node_dashboard_layout -->|"contains"| node_node_reports_page
node_node_dashboard_layout -->|"contains"| node_node_customers_page
node_node_dashboard_layout -->|"contains"| node_node_suppliers_page
node_node_dashboard_layout -->|"contains"| node_node_returns_page
node_node_dashboard_layout -->|"contains"| node_node_expenses_page
node_node_dashboard_layout -->|"contains"| node_node_other_customers_page
node_node_dashboard_layout -->|"contains"| node_node_categories_page
node_node_dashboard_layout -->|"contains"| node_node_users_page
node_node_dashboard_layout -->|"contains"| node_node_settings_page
node_node_dashboard_home -->|"fetches data"| node_node_api
node_node_products_page -->|"fetches data"| node_node_api
node_node_inventory_page -->|"fetches data"| node_node_api
node_node_purchases_page -->|"fetches data"| node_node_api
node_node_pos_page -->|"fetches data"| node_node_api
node_node_pos_page -->|"prints receipts"| node_node_receipt_print
node_node_reports_page -->|"fetches data"| node_node_api
node_node_customers_page -->|"fetches data"| node_node_api
node_node_suppliers_page -->|"fetches data"| node_node_api
node_node_returns_page -->|"fetches data"| node_node_api
node_node_expenses_page -->|"fetches data"| node_node_api
node_node_settings_page -->|"fetches data"| node_node_api
node_node_ui_primitives -->|"shares helpers"| node_node_utils
node_node_ui_primitives -->|"consumed by"| node_node_providers
node_node_i18n -->|"controlled by"| node_node_language_switcher
node_node_providers -->|"provides"| node_node_i18n
node_node_providers -->|"provides"| node_node_use_auth

click node_node_electron_main "https://github.com/0xissam/business-flow-frontend/blob/main/electron/main.js"
click node_node_electron_preload "https://github.com/0xissam/business-flow-frontend/blob/main/electron/preload.js"
click node_node_root_layout "https://github.com/0xissam/business-flow-frontend/blob/main/src/app/layout.tsx"
click node_node_root_page "https://github.com/0xissam/business-flow-frontend/blob/main/src/app/page.tsx"
click node_node_auth_login "https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(auth)/login/page.tsx"
click node_node_dashboard_layout "https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/layout.tsx"
click node_node_dashboard_home "https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/dashboard/page.tsx"
click node_node_products_page "https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/products/page.tsx"
click node_node_inventory_page "https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/inventory/page.tsx"
click node_node_purchases_page "https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/purchases/page.tsx"
click node_node_pos_page "https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/pos/page.tsx"
click node_node_reports_page "https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/reports/page.tsx"
click node_node_customers_page "https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/customers/page.tsx"
click node_node_suppliers_page "https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/suppliers/page.tsx"
click node_node_returns_page "https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/returns/page.tsx"
click node_node_expenses_page "https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/expenses/page.tsx"
click node_node_other_customers_page "https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/other-customers/page.tsx"
click node_node_categories_page "https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/categories/page.tsx"
click node_node_users_page "https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/users/page.tsx"
click node_node_settings_page "https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/settings/page.tsx"
click node_node_sidebar "https://github.com/0xissam/business-flow-frontend/blob/main/src/components/sidebar.tsx"
click node_node_language_switcher "https://github.com/0xissam/business-flow-frontend/blob/main/src/components/language-switcher.tsx"
click node_node_ui_primitives "https://github.com/0xissam/business-flow-frontend/tree/main/src/components/ui"
click node_node_use_auth "https://github.com/0xissam/business-flow-frontend/blob/main/src/hooks/useAuth.tsx"
click node_node_api "https://github.com/0xissam/business-flow-frontend/blob/main/src/lib/api.ts"
click node_node_receipt_print "https://github.com/0xissam/business-flow-frontend/blob/main/src/lib/receipt-print.ts"
click node_node_i18n "https://github.com/0xissam/business-flow-frontend/blob/main/src/lib/i18n.tsx"
click node_node_utils "https://github.com/0xissam/business-flow-frontend/blob/main/src/lib/utils.ts"
click node_node_providers "https://github.com/0xissam/business-flow-frontend/blob/main/src/providers/index.tsx"
click node_node_globals_css "https://github.com/0xissam/business-flow-frontend/blob/main/src/app/globals.css"

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_node_electron_main,node_node_electron_preload toneBlue
class node_node_root_layout,node_node_root_page,node_node_auth_login,node_node_dashboard_layout,node_node_dashboard_home,node_node_products_page,node_node_inventory_page,node_node_purchases_page,node_node_pos_page,node_node_reports_page,node_node_customers_page,node_node_suppliers_page,node_node_returns_page,node_node_expenses_page,node_node_other_customers_page,node_node_categories_page,node_node_users_page,node_node_settings_page toneAmber
class node_node_sidebar,node_node_language_switcher,node_node_ui_primitives,node_node_use_auth,node_node_api,node_node_receipt_print,node_node_i18n,node_node_utils toneMint
class node_node_providers,node_node_globals_css toneRose
```

## Components

### Electron

Desktop runtime and preload bridge

- [Main process](https://github.com/0xissam/business-flow-frontend/blob/main/electron/main.js): electron-main · Desktop app entrypoint and window lifecycle · `electron/main.js`
- [Preload bridge](https://github.com/0xissam/business-flow-frontend/blob/main/electron/preload.js): electron-preload · Safe bridge between renderer and desktop APIs · `electron/preload.js`

### Next app

App Router routes and layouts

- [Root layout](https://github.com/0xissam/business-flow-frontend/blob/main/src/app/layout.tsx): next-layout · Top-level app shell for the Next renderer · `src/app/layout.tsx`
- [Landing page](https://github.com/0xissam/business-flow-frontend/blob/main/src/app/page.tsx): route-page · Top-level entry route · `src/app/page.tsx`
- [Login](https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(auth)/login/page.tsx): auth-route · Unauthenticated sign-in flow · `src/app/(auth)/login/page.tsx`
- [Dashboard shell](https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/layout.tsx): dashboard-layout · Shared chrome and navigation for business pages · `src/app/(dashboard)/layout.tsx`
- [Dashboard home](https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/dashboard/page.tsx): module-page · Main overview page inside the dashboard area · `src/app/(dashboard)/dashboard/page.tsx`
- [Products](https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/products/page.tsx): module-page · Product management entrypoint · `src/app/(dashboard)/products/page.tsx`
- [Inventory](https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/inventory/page.tsx): module-page · Stock and inventory workflows · `src/app/(dashboard)/inventory/page.tsx`
- [Purchases](https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/purchases/page.tsx): module-page · Procurement and buying workflows · `src/app/(dashboard)/purchases/page.tsx`
- [POS](https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/pos/page.tsx): module-page · Point-of-sale register workflow · `src/app/(dashboard)/pos/page.tsx`
- [Reports](https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/reports/page.tsx): module-page · Reporting and analytics entrypoint · `src/app/(dashboard)/reports/page.tsx`
- [Customers](https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/customers/page.tsx): module-page · Customer management page · `src/app/(dashboard)/customers/page.tsx`
- [Suppliers](https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/suppliers/page.tsx): module-page · Supplier management page · `src/app/(dashboard)/suppliers/page.tsx`
- [Returns](https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/returns/page.tsx): module-page · Returns processing page · `src/app/(dashboard)/returns/page.tsx`
- [Expenses](https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/expenses/page.tsx): module-page · Expense tracking page · `src/app/(dashboard)/expenses/page.tsx`
- [Other customers](https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/other-customers/page.tsx): module-page · Secondary customer-related workflow · `src/app/(dashboard)/other-customers/page.tsx`
- [Categories](https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/categories/page.tsx): module-page · Product category management page · `src/app/(dashboard)/categories/page.tsx`
- [Users](https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/users/page.tsx): admin-page · User and access management page · `src/app/(dashboard)/users/page.tsx`
- [Settings](https://github.com/0xissam/business-flow-frontend/blob/main/src/app/(dashboard)/settings/page.tsx): settings-page · Application configuration page · `src/app/(dashboard)/settings/page.tsx`

### Shared UI

Reusable presentation and cross-cutting app code

- [Sidebar](https://github.com/0xissam/business-flow-frontend/blob/main/src/components/sidebar.tsx): nav-shell · Dashboard navigation component · `src/components/sidebar.tsx`
- [Language switcher](https://github.com/0xissam/business-flow-frontend/blob/main/src/components/language-switcher.tsx): i18n-ui · Runtime language selection control · `src/components/language-switcher.tsx`
- [UI primitives](https://github.com/0xissam/business-flow-frontend/tree/main/src/components/ui): component-kit · Reusable buttons, inputs, tables, dialogs, and form controls · `src/components/ui`
- [Auth hook](https://github.com/0xissam/business-flow-frontend/blob/main/src/hooks/useAuth.tsx): state-hook · Client-side authentication/session state · `src/hooks/useAuth.tsx`
- [API client](https://github.com/0xissam/business-flow-frontend/blob/main/src/lib/api.ts): integration-client · Central backend communication layer · `src/lib/api.ts`
- [Receipt print](https://github.com/0xissam/business-flow-frontend/blob/main/src/lib/receipt-print.ts): printing-integration · Printing workflow for POS and register use · `src/lib/receipt-print.ts`
- [i18n](https://github.com/0xissam/business-flow-frontend/blob/main/src/lib/i18n.tsx): locale-runtime · Localization setup and runtime language plumbing · `src/lib/i18n.tsx`
- [Utils](https://github.com/0xissam/business-flow-frontend/blob/main/src/lib/utils.ts): shared-utils · General shared helpers · `src/lib/utils.ts`

### Platform

Root-level styling and provider composition

- [Providers](https://github.com/0xissam/business-flow-frontend/blob/main/src/providers/index.tsx): app-providers · Global provider composition for the app · `src/providers/index.tsx`
- [Global styles](https://github.com/0xissam/business-flow-frontend/blob/main/src/app/globals.css): styling · App-wide Tailwind/CSS entrypoint · `src/app/globals.css`

## Connections

- Main process → Preload bridge: loads bridge · Desktop runtime exposes renderer bridge through preload
- Main process → Root layout: hosts UI · Electron launches the Next renderer shell
- Root layout → Providers: wraps with · Root layout composes global providers
- Root layout → Global styles: imports styles · Global styling is applied at the root
- Root layout → Landing page: renders route · Top-level landing route sits under the root layout
- Root layout → Login: routes to · Unauthenticated flow is part of the app router
- Root layout → Dashboard shell: routes to · Authenticated application area is nested under dashboard layout
- Dashboard shell → Sidebar: uses · Dashboard shell includes persistent navigation
- Dashboard shell → Auth hook: guards with · Dashboard access depends on auth/session state
- Dashboard shell → Language switcher: includes · Shell exposes language control
- Dashboard shell → Dashboard home: contains · Dashboard area includes an overview page
- Dashboard shell → Products: contains · Business module route
- Dashboard shell → Inventory: contains · Business module route
- Dashboard shell → Purchases: contains · Business module route
- Dashboard shell → POS: contains · Business module route
- Dashboard shell → Reports: contains · Business module route
- Dashboard shell → Customers: contains · Business module route
- Dashboard shell → Suppliers: contains · Business module route
- Dashboard shell → Returns: contains · Business module route
- Dashboard shell → Expenses: contains · Business module route
- Dashboard shell → Other customers: contains · Secondary business route
- Dashboard shell → Categories: contains · Catalog structure route
- Dashboard shell → Users: contains · Admin route
- Dashboard shell → Settings: contains · Configuration route
- Dashboard home → API client: fetches data · Dashboard pages rely on centralized backend access
- Products → API client: fetches data · Module pages use the API client
- Inventory → API client: fetches data · Module pages use the API client
- Purchases → API client: fetches data · Module pages use the API client
- POS → API client: fetches data · POS communicates with backend services
- POS → Receipt print: prints receipts · Register workflow depends on print integration
- Reports → API client: fetches data · Reporting reads from backend services
- Customers → API client: fetches data · Module pages use the API client
- Suppliers → API client: fetches data · Module pages use the API client
- Returns → API client: fetches data · Module pages use the API client
- Expenses → API client: fetches data · Module pages use the API client
- Settings → API client: fetches data · Settings may persist through backend APIs
- UI primitives → Utils: shares helpers · Reusable components use common helper logic
- UI primitives → Providers: consumed by · Provider-managed UI uses shared primitives
- i18n → Language switcher: controlled by · Language UI drives locale runtime
- Providers → i18n: provides · Global providers likely assemble locale context
- Providers → Auth hook: provides · Global providers likely expose auth context
