# kjmbibang/cartsense architecture

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

- Interactive diagram: https://gitdiagram.com/kjmbibang/cartsense
- Repository: https://github.com/kjmbibang/cartsense

## Overview

CartSense imports grocery-order CSVs, validates and stores order lines, then generates an order-level basket-analysis payload that powers a scoped analytics workspace. The documented Python workflow covers preprocessing, user-disjoint holdout evaluation, Apriori mining, and recommendations with a popularity fallback; the UI exposes dashboard, behavior, product, bundle, network, reliability, and export views. The API also supports import history, deletion, and filtered data checks. Some route and pipeline internals were not shown, so unverified runtime links are omitted or marked dashed.

Main entry points: [`src/client/AnalysisScreen.jsx`](https://github.com/kjmbibang/cartsense/blob/main/src/client/AnalysisScreen.jsx) (Payload views), [`server/routes/uploads.js`](https://github.com/kjmbibang/cartsense/blob/main/server/routes/uploads.js) (Upload jobs), [`server/routes/analysis.js`](https://github.com/kjmbibang/cartsense/blob/main/server/routes/analysis.js) (Analysis routes), [`src/client/api.js`](https://github.com/kjmbibang/cartsense/blob/main/src/client/api.js) (HTTP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Analytics workspace"]
  node_app["Screen navigation<br/>[App.jsx]"]
  node_upload["Upload and scope"]
  node_shared["Payload views<br/>[AnalysisScreen.jsx]"]
  node_dashboard["Executive dashboard"]
  node_behavior["Behavior insights"]
  node_buying["Buying patterns<br/>[BuyingPatterns.jsx]"]
  node_bundles["Bundle opportunities"]
  node_network["Association network"]
  node_reliability["Reliability report"]
  node_products["Product explorer"]
  node_departments["Department insights"]
  node_how["Method trace<br/>[HowItWorks.jsx]"]
  node_exports["Reports and export<br/>[ReportsExport.jsx]"]
  node_api_client["HTTP client<br/>[api.js]"]
end

subgraph group_api["Import and API"]
  node_server["Express API<br/>[index.js]"]
  node_upload_routes["Upload jobs<br/>[uploads.js]"]
  node_analysis_routes["Analysis routes<br/>[analysis.js]"]
  node_importer["CSV importer<br/>[importOrders.js]"]
end

subgraph group_analysis["Basket analysis"]
  node_pipeline["Payload pipeline"]
  node_python_cli["Python CLI<br/>[cli.py]"]
  node_basket_analysis["Basket analysis<br/>[analysis.py]"]
end

subgraph group_storage["Persistence"]
  node_payload_store["Payload file store<br/>[analysisPayload.js]"]
  node_db_access["MySQL access<br/>[database.js]"]
  node_mysql[("MySQL tables<br/>[schema.sql]")]
end

node_analyst(("Analyst"))

node_analyst -->|"uses"| node_app
node_app -->|"selects screen"| node_upload
node_app -->|"selects screen"| node_dashboard
node_upload -->|"requests imports"| node_api_client
node_shared -->|"loads payload"| node_api_client
node_dashboard -->|"renders"| node_shared
node_behavior -->|"renders"| node_shared
node_buying -->|"renders"| node_shared
node_bundles -->|"renders"| node_shared
node_network -->|"renders"| node_shared
node_reliability -->|"renders"| node_shared
node_products -->|"renders"| node_shared
node_departments -->|"renders"| node_shared
node_how -->|"renders"| node_shared
node_exports -->|"renders"| node_shared
node_api_client -->|"uploads and polls"| node_upload_routes
node_api_client -->|"requests analysis"| node_analysis_routes
node_server -->|"mounts routes"| node_upload_routes
node_server -->|"mounts routes"| node_analysis_routes
node_upload_routes -->|"imports rows"| node_importer
node_upload_routes -->|"publishes analysis"| node_pipeline
node_upload_routes -->|"checks database"| node_db_access
node_analysis_routes -->|"generates scoped payload"| node_pipeline
node_analysis_routes -->|"reads and saves"| node_payload_store
node_importer -->|"writes imports"| node_db_access
node_pipeline -.->|"runs analysis"| node_python_cli
node_python_cli -->|"builds payload"| node_basket_analysis
node_pipeline -->|"publishes payload"| node_payload_store
node_analysis_routes -->|"queries imports"| node_db_access
node_db_access -->|"connects to"| node_mysql

click node_app "https://github.com/kjmbibang/cartsense/blob/main/src/App.jsx"
click node_upload "https://github.com/kjmbibang/cartsense/blob/main/src/client/screens/UploadDataCheck.jsx"
click node_shared "https://github.com/kjmbibang/cartsense/blob/main/src/client/AnalysisScreen.jsx"
click node_dashboard "https://github.com/kjmbibang/cartsense/blob/main/src/client/screens/ExecutiveDashboard.jsx"
click node_behavior "https://github.com/kjmbibang/cartsense/blob/main/src/client/screens/ShoppingBehavior.jsx"
click node_buying "https://github.com/kjmbibang/cartsense/blob/main/src/client/screens/BuyingPatterns.jsx"
click node_bundles "https://github.com/kjmbibang/cartsense/blob/main/src/client/screens/BundleOpportunities.jsx"
click node_network "https://github.com/kjmbibang/cartsense/blob/main/src/client/screens/AssociationNetwork.jsx"
click node_reliability "https://github.com/kjmbibang/cartsense/blob/main/src/client/screens/ReliabilityReport.jsx"
click node_products "https://github.com/kjmbibang/cartsense/blob/main/src/client/screens/ProductExplorer.jsx"
click node_departments "https://github.com/kjmbibang/cartsense/blob/main/src/client/screens/DepartmentInsights.jsx"
click node_how "https://github.com/kjmbibang/cartsense/blob/main/src/client/screens/HowItWorks.jsx"
click node_exports "https://github.com/kjmbibang/cartsense/blob/main/src/client/screens/ReportsExport.jsx"
click node_api_client "https://github.com/kjmbibang/cartsense/blob/main/src/client/api.js"
click node_server "https://github.com/kjmbibang/cartsense/blob/main/server/index.js"
click node_upload_routes "https://github.com/kjmbibang/cartsense/blob/main/server/routes/uploads.js"
click node_analysis_routes "https://github.com/kjmbibang/cartsense/blob/main/server/routes/analysis.js"
click node_importer "https://github.com/kjmbibang/cartsense/blob/main/server/services/importOrders.js"
click node_pipeline "https://github.com/kjmbibang/cartsense/blob/main/server/services/analysisPipeline.js"
click node_python_cli "https://github.com/kjmbibang/cartsense/blob/main/python/cartsense_analysis/cli.py"
click node_basket_analysis "https://github.com/kjmbibang/cartsense/blob/main/python/cartsense_analysis/analysis.py"
click node_payload_store "https://github.com/kjmbibang/cartsense/blob/main/server/services/analysisPayload.js"
click node_db_access "https://github.com/kjmbibang/cartsense/blob/main/server/config/database.js"
click node_mysql "https://github.com/kjmbibang/cartsense/blob/main/server/sql/schema.sql"

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_upload,node_shared,node_dashboard,node_behavior,node_buying,node_bundles,node_network,node_reliability,node_products,node_departments,node_how,node_exports,node_api_client toneBlue
class node_server,node_upload_routes,node_analysis_routes,node_importer toneAmber
class node_pipeline,node_python_cli,node_basket_analysis toneMint
class node_payload_store,node_db_access,node_mysql toneRose
class node_analyst toneIndigo
```

## Components

### Analytics workspace

- [Screen navigation](https://github.com/kjmbibang/cartsense/blob/main/src/App.jsx): `src/App.jsx`
- [Upload and scope](https://github.com/kjmbibang/cartsense/blob/main/src/client/screens/UploadDataCheck.jsx): `src/client/screens/UploadDataCheck.jsx`
- [Payload views](https://github.com/kjmbibang/cartsense/blob/main/src/client/AnalysisScreen.jsx): `src/client/AnalysisScreen.jsx`
- [Executive dashboard](https://github.com/kjmbibang/cartsense/blob/main/src/client/screens/ExecutiveDashboard.jsx): `src/client/screens/ExecutiveDashboard.jsx`
- [Behavior insights](https://github.com/kjmbibang/cartsense/blob/main/src/client/screens/ShoppingBehavior.jsx): `src/client/screens/ShoppingBehavior.jsx`
- [Buying patterns](https://github.com/kjmbibang/cartsense/blob/main/src/client/screens/BuyingPatterns.jsx): `src/client/screens/BuyingPatterns.jsx`
- [Bundle opportunities](https://github.com/kjmbibang/cartsense/blob/main/src/client/screens/BundleOpportunities.jsx): `src/client/screens/BundleOpportunities.jsx`
- [Association network](https://github.com/kjmbibang/cartsense/blob/main/src/client/screens/AssociationNetwork.jsx): `src/client/screens/AssociationNetwork.jsx`
- [Reliability report](https://github.com/kjmbibang/cartsense/blob/main/src/client/screens/ReliabilityReport.jsx): `src/client/screens/ReliabilityReport.jsx`
- [Product explorer](https://github.com/kjmbibang/cartsense/blob/main/src/client/screens/ProductExplorer.jsx): `src/client/screens/ProductExplorer.jsx`
- [Department insights](https://github.com/kjmbibang/cartsense/blob/main/src/client/screens/DepartmentInsights.jsx): `src/client/screens/DepartmentInsights.jsx`
- [Method trace](https://github.com/kjmbibang/cartsense/blob/main/src/client/screens/HowItWorks.jsx): `src/client/screens/HowItWorks.jsx`
- [Reports and export](https://github.com/kjmbibang/cartsense/blob/main/src/client/screens/ReportsExport.jsx): `src/client/screens/ReportsExport.jsx`
- [HTTP client](https://github.com/kjmbibang/cartsense/blob/main/src/client/api.js): `src/client/api.js`

### Import and API

- [Express API](https://github.com/kjmbibang/cartsense/blob/main/server/index.js): `server/index.js`
- [Upload jobs](https://github.com/kjmbibang/cartsense/blob/main/server/routes/uploads.js): `server/routes/uploads.js`
- [Analysis routes](https://github.com/kjmbibang/cartsense/blob/main/server/routes/analysis.js): `server/routes/analysis.js`
- [CSV importer](https://github.com/kjmbibang/cartsense/blob/main/server/services/importOrders.js): `server/services/importOrders.js`

### Basket analysis

- [Payload pipeline](https://github.com/kjmbibang/cartsense/blob/main/server/services/analysisPipeline.js): `server/services/analysisPipeline.js`
- [Python CLI](https://github.com/kjmbibang/cartsense/blob/main/python/cartsense_analysis/cli.py): `python/cartsense_analysis/cli.py`
- [Basket analysis](https://github.com/kjmbibang/cartsense/blob/main/python/cartsense_analysis/analysis.py): `python/cartsense_analysis/analysis.py`

### Persistence

- [Payload file store](https://github.com/kjmbibang/cartsense/blob/main/server/services/analysisPayload.js): `server/services/analysisPayload.js`
- [MySQL access](https://github.com/kjmbibang/cartsense/blob/main/server/config/database.js): `server/config/database.js`
- [MySQL tables](https://github.com/kjmbibang/cartsense/blob/main/server/sql/schema.sql): `server/sql/schema.sql`

### Other components

- **Analyst**

## Connections

- Analyst → Screen navigation: uses (evidence: `README.md`)
- Screen navigation → Upload and scope: selects screen (evidence: `src/App.jsx`)
- Screen navigation → Executive dashboard: selects screen (evidence: `src/App.jsx`)
- Upload and scope → HTTP client: requests imports (evidence: `src/client/screens/UploadDataCheck.jsx`)
- Payload views → HTTP client: loads payload (evidence: `src/client/AnalysisScreen.jsx`)
- Executive dashboard → Payload views: renders (evidence: `src/client/screens/ExecutiveDashboard.jsx`)
- Behavior insights → Payload views: renders (evidence: `src/client/screens/ShoppingBehavior.jsx`)
- Buying patterns → Payload views: renders (evidence: `src/client/screens/BuyingPatterns.jsx`)
- Bundle opportunities → Payload views: renders (evidence: `src/client/screens/BundleOpportunities.jsx`)
- Association network → Payload views: renders (evidence: `src/client/screens/AssociationNetwork.jsx`)
- Reliability report → Payload views: renders (evidence: `src/client/screens/ReliabilityReport.jsx`)
- Product explorer → Payload views: renders (evidence: `src/client/screens/ProductExplorer.jsx`)
- Department insights → Payload views: renders (evidence: `src/client/screens/DepartmentInsights.jsx`)
- Method trace → Payload views: renders (evidence: `src/client/screens/HowItWorks.jsx`)
- Reports and export → Payload views: renders (evidence: `src/client/screens/ReportsExport.jsx`)
- HTTP client → Upload jobs: uploads and polls (evidence: `src/client/api.js`)
- HTTP client → Analysis routes: requests analysis (evidence: `src/client/api.js`)
- Express API → Upload jobs: mounts routes (evidence: `server/index.js`)
- Express API → Analysis routes: mounts routes (evidence: `server/index.js`)
- Upload jobs → CSV importer: imports rows (evidence: `server/routes/uploads.js`)
- Upload jobs → Payload pipeline: publishes analysis (evidence: `server/routes/uploads.js`)
- Upload jobs → MySQL access: checks database (evidence: `server/routes/uploads.js`)
- Analysis routes → Payload pipeline: generates scoped payload (evidence: `server/routes/analysis.js`)
- Analysis routes → Payload file store: reads and saves (evidence: `server/routes/analysis.js`)
- CSV importer → MySQL access: writes imports (evidence: `server/services/importOrders.js`)
- Payload pipeline → Python CLI: runs analysis
- Python CLI → Basket analysis: builds payload (evidence: `python/cartsense_analysis/cli.py`)
- Payload pipeline → Payload file store: publishes payload (evidence: `server/services/analysisPipeline.js`)
- Analysis routes → MySQL access: queries imports (evidence: `server/routes/analysis.js`)
- MySQL access → MySQL tables: connects to (evidence: `server/config/database.js`)