# speedster150/retailpilot-ai architecture

> Architecture diagram of the GitHub repository speedster150/retailpilot-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/speedster150/retailpilot-ai
- Repository: https://github.com/speedster150/retailpilot-ai

## Overview

This appears to be a multi-tenant retail operations workspace: staff manage inventory, purchasing, suppliers, goods receipts, sales and related business records; reporting, automation and AI/MCP interfaces provide analysis and actions. The graph follows evidenced route-to-handler and service calls, plus the shared stock, finance and reporting layers. Several dashboard capabilities are represented from the file tree, but their internal wiring is not asserted because those sources were not sampled; the README is a generic Next.js starter.

Main entry points: [`lib/inventory/stock.ts`](https://github.com/speedster150/retailpilot-ai/blob/master/lib/inventory/stock.ts) (Stock Engine), [`lib/mcp/server.ts`](https://github.com/speedster150/retailpilot-ai/blob/master/lib/mcp/server.ts) (MCP Server), [`lib/automation/low-stock-alert.ts`](https://github.com/speedster150/retailpilot-ai/blob/master/lib/automation/low-stock-alert.ts) (Low Stock Alerts), [`lib/supabase/server.ts`](https://github.com/speedster150/retailpilot-ai/blob/master/lib/supabase/server.ts) (Supabase Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operations["Retail Operations"]
  node_workspace["Workspace Pages<br/>[page.tsx]"]
  node_inventoryui["Inventory<br/>[page.tsx]"]
  node_purchases["Purchases"]
  node_receipts["Goods Receipts"]
  node_suppliers["Suppliers"]
  node_sales["Sales POS<br/>[pos-terminal.tsx]"]
  node_customers["Customers"]
  node_otherops["Other Operations"]
end

subgraph group_insights["Analytics Automation"]
  node_stock["Stock Engine<br/>[stock.ts]"]
  node_deadstock["Dead Stock<br/>[dead-stock.ts]"]
  node_profitability["Profitability<br/>[profitability.ts]"]
  node_outstanding["Supplier Outstanding"]
  node_businessreport["Business Reports<br/>[business-report.ts]"]
  node_automationroutes["Automation Routes"]
  node_daily["Daily Dossier"]
  node_lowstock["Low Stock Alerts<br/>[low-stock-alert.ts]"]
  node_deadstockaudit["Dead Stock Audit"]
  node_monthly["Monthly Report"]
  node_escalation["Supplier Escalation"]
end

subgraph group_intelligence["AI MCP"]
  node_ai["AI Assistant<br/>[assistant.ts]"]
  node_mcpapi["MCP Endpoint<br/>[route.ts]"]
  node_mcpserver["MCP Server<br/>[server.ts]"]
  node_registry["MCP Registry<br/>[registry.ts]"]
  node_chatapi["Chat Endpoint<br/>[route.ts]"]
end

subgraph group_platform["Identity Data"]
  node_auth["Tenant Context<br/>[context.ts]"]
  node_supabase["Supabase Client<br/>[server.ts]"]
  node_database[("Supabase")]
end

node_staff(("Staff"))

node_staff -.->|"uses"| node_workspace
node_workspace -.->|"navigates"| node_inventoryui
node_inventoryui -->|"uses"| node_stock
node_inventoryui -->|"queries"| node_supabase
node_purchases -.->|"records receipts"| node_receipts
node_receipts -.->|"uses"| node_supabase
node_purchases -.->|"uses"| node_supabase
node_suppliers -.->|"uses"| node_supabase
node_stock -.->|"reads inventory"| node_database
node_deadstock -->|"calculates stock"| node_stock
node_profitability -->|"uses"| node_stock
node_outstanding -->|"uses"| node_stock
node_businessreport -->|"uses"| node_stock
node_businessreport -->|"uses"| node_deadstock
node_businessreport -->|"uses"| node_outstanding
node_automationroutes -->|"dispatches"| node_daily
node_automationroutes -->|"dispatches"| node_lowstock
node_automationroutes -->|"dispatches"| node_deadstockaudit
node_automationroutes -->|"dispatches"| node_monthly
node_automationroutes -->|"dispatches"| node_escalation
node_daily -->|"uses"| node_stock
node_daily -->|"uses"| node_lowstock
node_lowstock -->|"calculates stock"| node_stock
node_deadstockaudit -->|"uses"| node_deadstock
node_deadstockaudit -->|"uses"| node_lowstock
node_monthly -->|"uses"| node_businessreport
node_monthly -->|"uses"| node_lowstock
node_escalation -->|"uses"| node_outstanding
node_escalation -->|"uses"| node_lowstock
node_chatapi -->|"authenticates"| node_auth
node_chatapi -->|"dispatches"| node_ai
node_ai -->|"executes tools"| node_registry
node_mcpapi -->|"authenticates"| node_auth
node_mcpapi -->|"creates server"| node_mcpserver
node_mcpserver -->|"queries"| node_stock
node_mcpserver -->|"queries"| node_deadstock
node_mcpserver -->|"queries"| node_profitability
node_mcpserver -->|"generates report"| node_businessreport
node_registry -->|"registers tools"| node_mcpserver
node_auth -->|"creates client"| node_supabase
node_supabase -.->|"connects"| node_database

click node_workspace "https://github.com/speedster150/retailpilot-ai/blob/master/app/(dashbaord)/dashboard/page.tsx"
click node_inventoryui "https://github.com/speedster150/retailpilot-ai/blob/master/app/(dashbaord)/inventory/page.tsx"
click node_purchases "https://github.com/speedster150/retailpilot-ai/blob/master/app/(dashbaord)/purchases/purchase-management.tsx"
click node_receipts "https://github.com/speedster150/retailpilot-ai/blob/master/app/(dashbaord)/goods-receipts/goods-receipt-management.tsx"
click node_suppliers "https://github.com/speedster150/retailpilot-ai/blob/master/app/(dashbaord)/suppliers/supplier-management.tsx"
click node_sales "https://github.com/speedster150/retailpilot-ai/blob/master/app/(dashbaord)/sales/pos-terminal.tsx"
click node_customers "https://github.com/speedster150/retailpilot-ai/blob/master/app/(dashbaord)/customers/customer-management.tsx"
click node_otherops "https://github.com/speedster150/retailpilot-ai/tree/master/app/(dashbaord)"
click node_stock "https://github.com/speedster150/retailpilot-ai/blob/master/lib/inventory/stock.ts"
click node_deadstock "https://github.com/speedster150/retailpilot-ai/blob/master/lib/inventory/dead-stock.ts"
click node_profitability "https://github.com/speedster150/retailpilot-ai/blob/master/lib/finance/profitability.ts"
click node_outstanding "https://github.com/speedster150/retailpilot-ai/blob/master/lib/finance/supplier-outstanding.ts"
click node_businessreport "https://github.com/speedster150/retailpilot-ai/blob/master/lib/reports/business-report.ts"
click node_automationroutes "https://github.com/speedster150/retailpilot-ai/tree/master/app/api/automation"
click node_daily "https://github.com/speedster150/retailpilot-ai/blob/master/lib/automation/daily-sales-dossier.ts"
click node_lowstock "https://github.com/speedster150/retailpilot-ai/blob/master/lib/automation/low-stock-alert.ts"
click node_deadstockaudit "https://github.com/speedster150/retailpilot-ai/blob/master/lib/automation/dead-stock-audit.ts"
click node_monthly "https://github.com/speedster150/retailpilot-ai/blob/master/lib/automation/monthly-executive-report.ts"
click node_escalation "https://github.com/speedster150/retailpilot-ai/blob/master/lib/automation/supplier-escalation.ts"
click node_ai "https://github.com/speedster150/retailpilot-ai/blob/master/lib/ai/assistant.ts"
click node_mcpapi "https://github.com/speedster150/retailpilot-ai/blob/master/app/api/mcp/route.ts"
click node_mcpserver "https://github.com/speedster150/retailpilot-ai/blob/master/lib/mcp/server.ts"
click node_registry "https://github.com/speedster150/retailpilot-ai/blob/master/lib/mcp/registry.ts"
click node_chatapi "https://github.com/speedster150/retailpilot-ai/blob/master/app/api/ai/chat/route.ts"
click node_auth "https://github.com/speedster150/retailpilot-ai/blob/master/lib/auth/context.ts"
click node_supabase "https://github.com/speedster150/retailpilot-ai/blob/master/lib/supabase/server.ts"

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_workspace,node_inventoryui,node_purchases,node_receipts,node_suppliers,node_sales,node_customers,node_otherops toneBlue
class node_stock,node_deadstock,node_profitability,node_outstanding,node_businessreport,node_automationroutes,node_daily,node_lowstock,node_deadstockaudit,node_monthly,node_escalation toneAmber
class node_ai,node_mcpapi,node_mcpserver,node_registry,node_chatapi toneMint
class node_auth,node_supabase,node_database toneRose
class node_staff toneIndigo
```

## Components

### Retail Operations

- [Workspace Pages](https://github.com/speedster150/retailpilot-ai/blob/master/app/(dashbaord)/dashboard/page.tsx): `app/(dashbaord)/dashboard/page.tsx`
- [Inventory](https://github.com/speedster150/retailpilot-ai/blob/master/app/(dashbaord)/inventory/page.tsx): `app/(dashbaord)/inventory/page.tsx`
- [Purchases](https://github.com/speedster150/retailpilot-ai/blob/master/app/(dashbaord)/purchases/purchase-management.tsx): `app/(dashbaord)/purchases/purchase-management.tsx`
- [Goods Receipts](https://github.com/speedster150/retailpilot-ai/blob/master/app/(dashbaord)/goods-receipts/goods-receipt-management.tsx): `app/(dashbaord)/goods-receipts/goods-receipt-management.tsx`
- [Suppliers](https://github.com/speedster150/retailpilot-ai/blob/master/app/(dashbaord)/suppliers/supplier-management.tsx): `app/(dashbaord)/suppliers/supplier-management.tsx`
- [Sales POS](https://github.com/speedster150/retailpilot-ai/blob/master/app/(dashbaord)/sales/pos-terminal.tsx): `app/(dashbaord)/sales/pos-terminal.tsx`
- [Customers](https://github.com/speedster150/retailpilot-ai/blob/master/app/(dashbaord)/customers/customer-management.tsx): `app/(dashbaord)/customers/customer-management.tsx`
- [Other Operations](https://github.com/speedster150/retailpilot-ai/tree/master/app/(dashbaord)): `app/(dashbaord)`

### Analytics Automation

- [Stock Engine](https://github.com/speedster150/retailpilot-ai/blob/master/lib/inventory/stock.ts): `lib/inventory/stock.ts`
- [Dead Stock](https://github.com/speedster150/retailpilot-ai/blob/master/lib/inventory/dead-stock.ts): `lib/inventory/dead-stock.ts`
- [Profitability](https://github.com/speedster150/retailpilot-ai/blob/master/lib/finance/profitability.ts): `lib/finance/profitability.ts`
- [Supplier Outstanding](https://github.com/speedster150/retailpilot-ai/blob/master/lib/finance/supplier-outstanding.ts): `lib/finance/supplier-outstanding.ts`
- [Business Reports](https://github.com/speedster150/retailpilot-ai/blob/master/lib/reports/business-report.ts): `lib/reports/business-report.ts`
- [Automation Routes](https://github.com/speedster150/retailpilot-ai/tree/master/app/api/automation): `app/api/automation`
- [Daily Dossier](https://github.com/speedster150/retailpilot-ai/blob/master/lib/automation/daily-sales-dossier.ts): `lib/automation/daily-sales-dossier.ts`
- [Low Stock Alerts](https://github.com/speedster150/retailpilot-ai/blob/master/lib/automation/low-stock-alert.ts): `lib/automation/low-stock-alert.ts`
- [Dead Stock Audit](https://github.com/speedster150/retailpilot-ai/blob/master/lib/automation/dead-stock-audit.ts): `lib/automation/dead-stock-audit.ts`
- [Monthly Report](https://github.com/speedster150/retailpilot-ai/blob/master/lib/automation/monthly-executive-report.ts): `lib/automation/monthly-executive-report.ts`
- [Supplier Escalation](https://github.com/speedster150/retailpilot-ai/blob/master/lib/automation/supplier-escalation.ts): `lib/automation/supplier-escalation.ts`

### AI MCP

- [AI Assistant](https://github.com/speedster150/retailpilot-ai/blob/master/lib/ai/assistant.ts): `lib/ai/assistant.ts`
- [MCP Endpoint](https://github.com/speedster150/retailpilot-ai/blob/master/app/api/mcp/route.ts): `app/api/mcp/route.ts`
- [MCP Server](https://github.com/speedster150/retailpilot-ai/blob/master/lib/mcp/server.ts): `lib/mcp/server.ts`
- [MCP Registry](https://github.com/speedster150/retailpilot-ai/blob/master/lib/mcp/registry.ts): `lib/mcp/registry.ts`
- [Chat Endpoint](https://github.com/speedster150/retailpilot-ai/blob/master/app/api/ai/chat/route.ts): `app/api/ai/chat/route.ts`

### Identity Data

- [Tenant Context](https://github.com/speedster150/retailpilot-ai/blob/master/lib/auth/context.ts): `lib/auth/context.ts`
- [Supabase Client](https://github.com/speedster150/retailpilot-ai/blob/master/lib/supabase/server.ts): `lib/supabase/server.ts`
- **Supabase**

### Other components

- **Staff**

## Connections

- Staff → Workspace Pages: uses
- Workspace Pages → Inventory: navigates
- Inventory → Stock Engine: uses (evidence: `app/(dashbaord)/inventory/page.tsx`)
- Inventory → Supabase Client: queries (evidence: `app/(dashbaord)/inventory/page.tsx`)
- Purchases → Goods Receipts: records receipts
- Goods Receipts → Supabase Client: uses
- Purchases → Supabase Client: uses
- Suppliers → Supabase Client: uses
- Stock Engine → Supabase: reads inventory
- Dead Stock → Stock Engine: calculates stock (evidence: `lib/inventory/dead-stock.ts`)
- Profitability → Stock Engine: uses (evidence: `lib/finance/profitability.ts`)
- Supplier Outstanding → Stock Engine: uses (evidence: `lib/finance/supplier-outstanding.ts`)
- Business Reports → Stock Engine: uses (evidence: `lib/reports/business-report.ts`)
- Business Reports → Dead Stock: uses (evidence: `lib/reports/business-report.ts`)
- Business Reports → Supplier Outstanding: uses (evidence: `lib/reports/business-report.ts`)
- Automation Routes → Daily Dossier: dispatches (evidence: `app/api/automation/daily-dossier/route.ts`)
- Automation Routes → Low Stock Alerts: dispatches (evidence: `app/api/automation/low-stock/route.ts`)
- Automation Routes → Dead Stock Audit: dispatches (evidence: `app/api/automation/dead-stock/route.ts`)
- Automation Routes → Monthly Report: dispatches (evidence: `app/api/automation/monthly-executive-report/route.ts`)
- Automation Routes → Supplier Escalation: dispatches (evidence: `app/api/automation/supplier-escalation/route.ts`)
- Daily Dossier → Stock Engine: uses (evidence: `lib/automation/daily-sales-dossier.ts`)
- Daily Dossier → Low Stock Alerts: uses (evidence: `lib/automation/daily-sales-dossier.ts`)
- Low Stock Alerts → Stock Engine: calculates stock (evidence: `lib/automation/low-stock-alert.ts`)
- Dead Stock Audit → Dead Stock: uses (evidence: `lib/automation/dead-stock-audit.ts`)
- Dead Stock Audit → Low Stock Alerts: uses (evidence: `lib/automation/dead-stock-audit.ts`)
- Monthly Report → Business Reports: uses (evidence: `lib/automation/monthly-executive-report.ts`)
- Monthly Report → Low Stock Alerts: uses (evidence: `lib/automation/monthly-executive-report.ts`)
- Supplier Escalation → Supplier Outstanding: uses (evidence: `lib/automation/supplier-escalation.ts`)
- Supplier Escalation → Low Stock Alerts: uses (evidence: `lib/automation/supplier-escalation.ts`)
- Chat Endpoint → Tenant Context: authenticates (evidence: `app/api/ai/chat/route.ts`)
- Chat Endpoint → AI Assistant: dispatches (evidence: `app/api/ai/chat/route.ts`)
- AI Assistant → MCP Registry: executes tools (evidence: `lib/ai/assistant.ts`)
- MCP Endpoint → Tenant Context: authenticates (evidence: `app/api/mcp/route.ts`)
- MCP Endpoint → MCP Server: creates server (evidence: `app/api/mcp/route.ts`)
- MCP Server → Stock Engine: queries (evidence: `lib/mcp/server.ts`)
- MCP Server → Dead Stock: queries (evidence: `lib/mcp/server.ts`)
- MCP Server → Profitability: queries (evidence: `lib/mcp/server.ts`)
- MCP Server → Business Reports: generates report (evidence: `lib/mcp/server.ts`)
- MCP Registry → MCP Server: registers tools (evidence: `lib/mcp/registry.ts`)
- Tenant Context → Supabase Client: creates client (evidence: `lib/auth/context.ts`)
- Supabase Client → Supabase: connects
