# john-michaelg135/web-pos architecture

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

- Interactive diagram: https://gitdiagram.com/john-michaelg135/web-pos
- Repository: https://github.com/john-michaelg135/web-pos

## Overview

This is a Next.js point-of-sale operations application. Staff authenticate through an Enterprise Portal, then use POS modules for sales processing, orders, products, stock, locations, starting cash, and manager reporting. The principal workflow is portal sign-in and session validation, followed by role- and location-scoped access to operational views backed by a shared POS API layer. The graph includes documented portal handoffs and sampled API relationships; several operational views are present in the tree but were not sampled, so their internal calls are not inferred.

Main entry points: [`app/api/probe/open/route.ts`](https://github.com/john-michaelg135/web-pos/blob/main/app/api/probe/open/route.ts) (Probe handoff), [`app/api/portal/callback/route.ts`](https://github.com/john-michaelg135/web-pos/blob/main/app/api/portal/callback/route.ts) (Portal callback), [`components/module-pos/api/api.ts`](https://github.com/john-michaelg135/web-pos/blob/main/components/module-pos/api/api.ts) (POS API client), [`app/api/portal/login/route.ts`](https://github.com/john-michaelg135/web-pos/blob/main/app/api/portal/login/route.ts) (Portal login)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and access"]
  node_login["Portal login<br/>[route.ts]"]
  node_callback["Portal callback<br/>[route.ts]"]
  node_portalclient["Portal client<br/>[client.ts]"]
  node_session[("POS session<br/>[config.ts]")]
  node_authcontext["Auth context<br/>[AuthContext.tsx]"]
  node_permissions["Role permissions<br/>[permissions.ts]"]
  node_probeopen["Probe handoff<br/>[route.ts]"]
end

subgraph group_operations["POS operations"]
  node_locationscope["Location scope<br/>[useMyLocations.ts]"]
  node_locationsapi["My locations API<br/>[route.ts]"]
  node_sales["Sales processing"]
  node_orders["Order management"]
  node_products["Product management"]
  node_stock["Stock management"]
  node_locations["Location management"]
  node_startingcash["Starting cash"]
  node_cashgate["Starting cash gate"]
  node_posapi["POS API client<br/>[api.ts]"]
end

subgraph group_reporting["Management reporting"]
  node_analytics["Sales analytics"]
  node_salesreport["Sales report<br/>[SalesReport.tsx]"]
end

subgraph group_platform["Application platform"]
  node_shell["Application shell<br/>[AppShell.tsx]"]
  node_skeleton["Page loading UI<br/>[PageSkeleton.tsx]"]
end

node_staff(("Staff member"))
node_portal{{"Enterprise Portal"}}
node_probe{{"POS Probe"}}

node_staff -->|"starts sign-in"| node_login
node_login -->|"redirects to authorize"| node_portal
node_portal -.->|"returns code"| node_callback
node_callback -->|"exchanges code"| node_portalclient
node_callback -->|"sets session cookie"| node_session
node_authcontext -->|"checks actions"| node_permissions
node_staff -->|"opens Probe"| node_probeopen
node_probeopen -.->|"rechecks access"| node_portalclient
node_probeopen -->|"fetches assigned branch"| node_posapi
node_probeopen -->|"redirects with handoff"| node_probe
node_locationscope -->|"fetches scope"| node_locationsapi
node_sales -->|"uses API client"| node_posapi
node_startingcash -.->|"uses gate"| node_cashgate
node_cashgate -->|"loads POS data"| node_posapi
node_analytics -.->|"renders report"| node_salesreport
node_staff -.->|"uses POS application"| node_shell
node_shell -.->|"shows loading UI"| node_skeleton

click node_login "https://github.com/john-michaelg135/web-pos/blob/main/app/api/portal/login/route.ts"
click node_callback "https://github.com/john-michaelg135/web-pos/blob/main/app/api/portal/callback/route.ts"
click node_portalclient "https://github.com/john-michaelg135/web-pos/blob/main/lib/portal/client.ts"
click node_session "https://github.com/john-michaelg135/web-pos/blob/main/lib/portal/config.ts"
click node_authcontext "https://github.com/john-michaelg135/web-pos/blob/main/context/AuthContext.tsx"
click node_permissions "https://github.com/john-michaelg135/web-pos/blob/main/lib/permissions.ts"
click node_probeopen "https://github.com/john-michaelg135/web-pos/blob/main/app/api/probe/open/route.ts"
click node_locationscope "https://github.com/john-michaelg135/web-pos/blob/main/lib/useMyLocations.ts"
click node_locationsapi "https://github.com/john-michaelg135/web-pos/blob/main/app/api/my-locations/route.ts"
click node_sales "https://github.com/john-michaelg135/web-pos/blob/main/pages/pos/ViewSalesProcessing.tsx"
click node_orders "https://github.com/john-michaelg135/web-pos/blob/main/pages/pos/ViewOrderManagement.tsx"
click node_products "https://github.com/john-michaelg135/web-pos/blob/main/pages/pos/ViewProductManagement.tsx"
click node_stock "https://github.com/john-michaelg135/web-pos/blob/main/pages/pos/ViewStockManagement.tsx"
click node_locations "https://github.com/john-michaelg135/web-pos/blob/main/pages/pos/ViewLocationsManagement.tsx"
click node_startingcash "https://github.com/john-michaelg135/web-pos/blob/main/pages/pos/ViewStartingCash.tsx"
click node_cashgate "https://github.com/john-michaelg135/web-pos/blob/main/components/module-pos/StartingCashGate.tsx"
click node_posapi "https://github.com/john-michaelg135/web-pos/blob/main/components/module-pos/api/api.ts"
click node_analytics "https://github.com/john-michaelg135/web-pos/blob/main/pages/pos/ViewSalesAnalytics.tsx"
click node_salesreport "https://github.com/john-michaelg135/web-pos/blob/main/components/module-pos/SalesReport.tsx"
click node_shell "https://github.com/john-michaelg135/web-pos/blob/main/components/shared/AppShell.tsx"
click node_skeleton "https://github.com/john-michaelg135/web-pos/blob/main/components/shared/PageSkeleton.tsx"

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_login,node_callback,node_portalclient,node_session,node_authcontext,node_permissions,node_probeopen toneBlue
class node_locationscope,node_locationsapi,node_sales,node_orders,node_products,node_stock,node_locations,node_startingcash,node_cashgate,node_posapi toneAmber
class node_analytics,node_salesreport toneMint
class node_shell,node_skeleton toneRose
class node_staff,node_portal,node_probe toneIndigo
```

## Components

### Identity and access

- [Portal login](https://github.com/john-michaelg135/web-pos/blob/main/app/api/portal/login/route.ts): `app/api/portal/login/route.ts`
- [Portal callback](https://github.com/john-michaelg135/web-pos/blob/main/app/api/portal/callback/route.ts): `app/api/portal/callback/route.ts`
- [Portal client](https://github.com/john-michaelg135/web-pos/blob/main/lib/portal/client.ts): `lib/portal/client.ts`
- [POS session](https://github.com/john-michaelg135/web-pos/blob/main/lib/portal/config.ts): `lib/portal/config.ts`
- [Auth context](https://github.com/john-michaelg135/web-pos/blob/main/context/AuthContext.tsx): `context/AuthContext.tsx`
- [Role permissions](https://github.com/john-michaelg135/web-pos/blob/main/lib/permissions.ts): `lib/permissions.ts`
- [Probe handoff](https://github.com/john-michaelg135/web-pos/blob/main/app/api/probe/open/route.ts): `app/api/probe/open/route.ts`

### POS operations

- [Location scope](https://github.com/john-michaelg135/web-pos/blob/main/lib/useMyLocations.ts): `lib/useMyLocations.ts`
- [My locations API](https://github.com/john-michaelg135/web-pos/blob/main/app/api/my-locations/route.ts): `app/api/my-locations/route.ts`
- [Sales processing](https://github.com/john-michaelg135/web-pos/blob/main/pages/pos/ViewSalesProcessing.tsx): `pages/pos/ViewSalesProcessing.tsx`
- [Order management](https://github.com/john-michaelg135/web-pos/blob/main/pages/pos/ViewOrderManagement.tsx): `pages/pos/ViewOrderManagement.tsx`
- [Product management](https://github.com/john-michaelg135/web-pos/blob/main/pages/pos/ViewProductManagement.tsx): `pages/pos/ViewProductManagement.tsx`
- [Stock management](https://github.com/john-michaelg135/web-pos/blob/main/pages/pos/ViewStockManagement.tsx): `pages/pos/ViewStockManagement.tsx`
- [Location management](https://github.com/john-michaelg135/web-pos/blob/main/pages/pos/ViewLocationsManagement.tsx): `pages/pos/ViewLocationsManagement.tsx`
- [Starting cash](https://github.com/john-michaelg135/web-pos/blob/main/pages/pos/ViewStartingCash.tsx): `pages/pos/ViewStartingCash.tsx`
- [Starting cash gate](https://github.com/john-michaelg135/web-pos/blob/main/components/module-pos/StartingCashGate.tsx): `components/module-pos/StartingCashGate.tsx`
- [POS API client](https://github.com/john-michaelg135/web-pos/blob/main/components/module-pos/api/api.ts): `components/module-pos/api/api.ts`

### Management reporting

- [Sales analytics](https://github.com/john-michaelg135/web-pos/blob/main/pages/pos/ViewSalesAnalytics.tsx): `pages/pos/ViewSalesAnalytics.tsx`
- [Sales report](https://github.com/john-michaelg135/web-pos/blob/main/components/module-pos/SalesReport.tsx): `components/module-pos/SalesReport.tsx`

### Application platform

- [Application shell](https://github.com/john-michaelg135/web-pos/blob/main/components/shared/AppShell.tsx): `components/shared/AppShell.tsx`
- [Page loading UI](https://github.com/john-michaelg135/web-pos/blob/main/components/shared/PageSkeleton.tsx): `components/shared/PageSkeleton.tsx`

### Other components

- **Staff member**
- **Enterprise Portal**
- **POS Probe**

## Connections

- Staff member → Portal login: starts sign-in (evidence: `app/api/portal/login/route.ts`)
- Portal login → Enterprise Portal: redirects to authorize (evidence: `app/api/portal/login/route.ts`)
- Enterprise Portal → Portal callback: returns code
- Portal callback → Portal client: exchanges code (evidence: `app/api/portal/callback/route.ts`)
- Portal callback → POS session: sets session cookie (evidence: `app/api/portal/callback/route.ts`)
- Auth context → Role permissions: checks actions (evidence: `context/AuthContext.tsx`)
- Staff member → Probe handoff: opens Probe (evidence: `app/api/probe/open/route.ts`)
- Probe handoff → Portal client: rechecks access
- Probe handoff → POS API client: fetches assigned branch (evidence: `app/api/probe/open/route.ts`)
- Probe handoff → POS Probe: redirects with handoff (evidence: `app/api/probe/open/route.ts`)
- Location scope → My locations API: fetches scope (evidence: `lib/useMyLocations.ts`)
- Sales processing → POS API client: uses API client (evidence: `pages/pos/ViewSalesProcessing.tsx`)
- Starting cash → Starting cash gate: uses gate
- Starting cash gate → POS API client: loads POS data (evidence: `components/module-pos/StartingCashGate.tsx`)
- Sales analytics → Sales report: renders report
- Staff member → Application shell: uses POS application
- Application shell → Page loading UI: shows loading UI
