# mahekagrwl/shopmind-ai architecture

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

- Interactive diagram: https://gitdiagram.com/mahekagrwl/shopmind-ai
- Repository: https://github.com/mahekagrwl/shopmind-ai

## Overview

ShopMind AI is a retail POS and store-management application. The main workflow is landing and authentication, store onboarding, then dashboard navigation to billing and operational features; the frontend calls a FastAPI backend that manages business data and analytics. The graph preserves the documented UI feature areas, including customer, reporting, and AI tools. Source excerpts show selected component calls and backend behavior; other UI relationships rely on the SOURCE INDEX, and unsampled backend routes are not expanded.

Main entry points: [`frontend/src/App.tsx`](https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/App.tsx) (App navigation), [`frontend/src/services/api.ts`](https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/services/api.ts) (API client), [`backend/main.py`](https://github.com/mahekagrwl/shopmind-ai/blob/main/backend/main.py) (FastAPI routes), [`frontend/src/components/LandingPage.tsx`](https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/LandingPage.tsx) (Landing page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry &amp; Setup"]
  node_landing["Landing page<br/>[LandingPage.tsx]"]
  node_auth["Authentication<br/>[AuthModal.tsx]"]
  node_onboard["Store onboarding"]
  node_categories["Category configuration<br/>[categories.ts]"]
end

subgraph group_operations["Retail Operations"]
  node_dashboard["Dashboard"]
  node_pos["POS checkout<br/>[POSView.tsx]"]
  node_products["Product catalog<br/>[ProductsView.tsx]"]
  node_inventory["Inventory<br/>[InventoryView.tsx]"]
  node_suppliers["Suppliers<br/>[SuppliersView.tsx]"]
  node_wastage["Wastage<br/>[WastageView.tsx]"]
  node_employees["Employees<br/>[EmployeesView.tsx]"]
  node_customers["Customers<br/>[CustomersView.tsx]"]
end

subgraph group_insights["Insights &amp; Engagement"]
  node_forecast["Demand forecasting"]
  node_simulator["What-if simulator"]
  node_reports["Reports<br/>[ReportsView.tsx]"]
  node_notifications["Notifications"]
  node_customerportal["Customer portal"]
  node_assistant["AI assistant"]
end

subgraph group_platform["Application &amp; API"]
  node_app["App navigation<br/>[App.tsx]"]
  node_api["API client<br/>[api.ts]"]
end

subgraph group_backend["Backend &amp; State"]
  node_backend_api["FastAPI routes<br/>[main.py]"]
  node_models["Domain models<br/>[models.py]"]
  node_db[("In-memory store<br/>[database.py]")]
end

node_shopper(("Shop owner / staff"))

node_shopper -->|"opens"| node_landing
node_shopper -->|"signs in"| node_auth
node_shopper -->|"sets up store"| node_onboard
node_landing -->|"uses categories"| node_categories
node_onboard -->|"uses categories"| node_categories
node_app -->|"renders"| node_landing
node_app -->|"renders"| node_auth
node_app -->|"renders"| node_onboard
node_app -->|"renders"| node_dashboard
node_app -->|"renders"| node_pos
node_app -->|"renders"| node_products
node_app -->|"renders"| node_inventory
node_app -->|"renders"| node_suppliers
node_app -->|"renders"| node_wastage
node_app -->|"renders"| node_employees
node_app -->|"renders"| node_customers
node_app -->|"renders"| node_forecast
node_app -->|"renders"| node_simulator
node_app -->|"renders"| node_reports
node_app -->|"renders"| node_notifications
node_app -->|"renders"| node_customerportal
node_app -->|"renders"| node_assistant
node_auth -->|"sends auth requests"| node_api
node_pos -->|"submits checkout"| node_api
node_products -->|"manages products"| node_api
node_inventory -->|"requests data"| node_api
node_suppliers -->|"requests data"| node_api
node_wastage -->|"requests data"| node_api
node_employees -->|"requests data"| node_api
node_customers -->|"requests data"| node_api
node_notifications -->|"requests data"| node_api
node_simulator -->|"requests data"| node_api
node_app -->|"loads store data"| node_api
node_api -->|"sends HTTP requests"| node_backend_api
node_backend_api -->|"validates payloads"| node_models
node_backend_api -->|"reads and writes"| node_db

click node_landing "https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/LandingPage.tsx"
click node_auth "https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/AuthModal.tsx"
click node_onboard "https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/OnboardingWizard.tsx"
click node_categories "https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/config/categories.ts"
click node_app "https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/App.tsx"
click node_dashboard "https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/DashboardOverview.tsx"
click node_pos "https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/POSView.tsx"
click node_products "https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/ProductsView.tsx"
click node_inventory "https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/InventoryView.tsx"
click node_suppliers "https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/SuppliersView.tsx"
click node_wastage "https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/WastageView.tsx"
click node_employees "https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/EmployeesView.tsx"
click node_customers "https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/CustomersView.tsx"
click node_forecast "https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/AIDemandForecastingView.tsx"
click node_simulator "https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/WhatIfSimulatorView.tsx"
click node_reports "https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/ReportsView.tsx"
click node_notifications "https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/NotificationsView.tsx"
click node_customerportal "https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/CustomerPortalView.tsx"
click node_assistant "https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/AIAssistantModal.tsx"
click node_api "https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/services/api.ts"
click node_backend_api "https://github.com/mahekagrwl/shopmind-ai/blob/main/backend/main.py"
click node_models "https://github.com/mahekagrwl/shopmind-ai/blob/main/backend/models.py"
click node_db "https://github.com/mahekagrwl/shopmind-ai/blob/main/backend/database.py"

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_landing,node_auth,node_onboard,node_categories toneBlue
class node_dashboard,node_pos,node_products,node_inventory,node_suppliers,node_wastage,node_employees,node_customers toneAmber
class node_forecast,node_simulator,node_reports,node_notifications,node_customerportal,node_assistant toneMint
class node_app,node_api toneRose
class node_backend_api,node_models,node_db,node_shopper toneIndigo
```

## Components

### Entry & Setup

- [Landing page](https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/LandingPage.tsx): `frontend/src/components/LandingPage.tsx`
- [Authentication](https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/AuthModal.tsx): `frontend/src/components/AuthModal.tsx`
- [Store onboarding](https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/OnboardingWizard.tsx): `frontend/src/components/OnboardingWizard.tsx`
- [Category configuration](https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/config/categories.ts): `frontend/src/config/categories.ts`

### Retail Operations

- [Dashboard](https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/DashboardOverview.tsx): `frontend/src/components/DashboardOverview.tsx`
- [POS checkout](https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/POSView.tsx): `frontend/src/components/POSView.tsx`
- [Product catalog](https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/ProductsView.tsx): `frontend/src/components/ProductsView.tsx`
- [Inventory](https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/InventoryView.tsx): `frontend/src/components/InventoryView.tsx`
- [Suppliers](https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/SuppliersView.tsx): `frontend/src/components/SuppliersView.tsx`
- [Wastage](https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/WastageView.tsx): `frontend/src/components/WastageView.tsx`
- [Employees](https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/EmployeesView.tsx): `frontend/src/components/EmployeesView.tsx`
- [Customers](https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/CustomersView.tsx): `frontend/src/components/CustomersView.tsx`

### Insights & Engagement

- [Demand forecasting](https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/AIDemandForecastingView.tsx): `frontend/src/components/AIDemandForecastingView.tsx`
- [What-if simulator](https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/WhatIfSimulatorView.tsx): `frontend/src/components/WhatIfSimulatorView.tsx`
- [Reports](https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/ReportsView.tsx): `frontend/src/components/ReportsView.tsx`
- [Notifications](https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/NotificationsView.tsx): `frontend/src/components/NotificationsView.tsx`
- [Customer portal](https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/CustomerPortalView.tsx): `frontend/src/components/CustomerPortalView.tsx`
- [AI assistant](https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/components/AIAssistantModal.tsx): `frontend/src/components/AIAssistantModal.tsx`

### Application & API

- [App navigation](https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/mahekagrwl/shopmind-ai/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### Backend & State

- [FastAPI routes](https://github.com/mahekagrwl/shopmind-ai/blob/main/backend/main.py): `backend/main.py`
- [Domain models](https://github.com/mahekagrwl/shopmind-ai/blob/main/backend/models.py): `backend/models.py`
- [In-memory store](https://github.com/mahekagrwl/shopmind-ai/blob/main/backend/database.py): `backend/database.py`

### Other components

- **Shop owner / staff**

## Connections

- Shop owner / staff → Landing page: opens (evidence: `frontend/src/components/LandingPage.tsx`)
- Shop owner / staff → Authentication: signs in (evidence: `frontend/src/components/AuthModal.tsx`)
- Shop owner / staff → Store onboarding: sets up store (evidence: `frontend/src/components/OnboardingWizard.tsx`)
- Landing page → Category configuration: uses categories (evidence: `frontend/src/components/LandingPage.tsx`)
- Store onboarding → Category configuration: uses categories (evidence: `frontend/src/components/OnboardingWizard.tsx`)
- App navigation → Landing page: renders (evidence: `frontend/src/App.tsx`)
- App navigation → Authentication: renders (evidence: `frontend/src/App.tsx`)
- App navigation → Store onboarding: renders (evidence: `frontend/src/App.tsx`)
- App navigation → Dashboard: renders (evidence: `frontend/src/App.tsx`)
- App navigation → POS checkout: renders (evidence: `frontend/src/App.tsx`)
- App navigation → Product catalog: renders (evidence: `frontend/src/App.tsx`)
- App navigation → Inventory: renders (evidence: `frontend/src/App.tsx`)
- App navigation → Suppliers: renders (evidence: `frontend/src/App.tsx`)
- App navigation → Wastage: renders (evidence: `frontend/src/App.tsx`)
- App navigation → Employees: renders (evidence: `frontend/src/App.tsx`)
- App navigation → Customers: renders (evidence: `frontend/src/App.tsx`)
- App navigation → Demand forecasting: renders (evidence: `frontend/src/App.tsx`)
- App navigation → What-if simulator: renders (evidence: `frontend/src/App.tsx`)
- App navigation → Reports: renders (evidence: `frontend/src/App.tsx`)
- App navigation → Notifications: renders (evidence: `frontend/src/App.tsx`)
- App navigation → Customer portal: renders (evidence: `frontend/src/App.tsx`)
- App navigation → AI assistant: renders (evidence: `frontend/src/App.tsx`)
- Authentication → API client: sends auth requests (evidence: `frontend/src/components/AuthModal.tsx`)
- POS checkout → API client: submits checkout (evidence: `frontend/src/components/POSView.tsx`)
- Product catalog → API client: manages products (evidence: `frontend/src/components/ProductsView.tsx`)
- Inventory → API client: requests data (evidence: `frontend/src/components/InventoryView.tsx`)
- Suppliers → API client: requests data (evidence: `frontend/src/components/SuppliersView.tsx`)
- Wastage → API client: requests data (evidence: `frontend/src/components/WastageView.tsx`)
- Employees → API client: requests data (evidence: `frontend/src/components/EmployeesView.tsx`)
- Customers → API client: requests data (evidence: `frontend/src/components/CustomersView.tsx`)
- Notifications → API client: requests data (evidence: `frontend/src/components/NotificationsView.tsx`)
- What-if simulator → API client: requests data (evidence: `frontend/src/components/WhatIfSimulatorView.tsx`)
- App navigation → API client: loads store data (evidence: `frontend/src/App.tsx`)
- API client → FastAPI routes: sends HTTP requests (evidence: `frontend/src/services/api.ts`)
- FastAPI routes → Domain models: validates payloads (evidence: `backend/main.py`)
- FastAPI routes → In-memory store: reads and writes (evidence: `backend/main.py`)
