# arunkumar7070/kjbn-sales_import_dashboard architecture

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

- Interactive diagram: https://gitdiagram.com/arunkumar7070/kjbn-sales_import_dashboard
- Repository: https://github.com/arunkumar7070/kjbn-sales_import_dashboard

## Overview

KJBN Sales Import & Dashboard is a React/FastAPI application for importing retail sales CSVs and exploring the resulting ledger and analytics. The principal workflow stages uploads through batch registration and background processing, parses and validates rows, applies sale/return rules, and persists results for reporting. The frontend also supports store-catalog imports, batch history, and transaction search. The README documents the main backend flow; sampled-source references support frontend relationships. Some implementation details are unsampled, so those links are omitted.

Main entry points: [`frontend/vite-project/src/api/client.ts`](https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/frontend/vite-project/src/api/client.ts) (API client), [`backend/app/models.py`](https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/backend/app/models.py) (Domain models), [`backend/api/routes.py`](https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/backend/api/routes.py) (API routes), [`frontend/vite-project/src/pages/IngestionPage.tsx`](https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/frontend/vite-project/src/pages/IngestionPage.tsx) (Ingestion page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_dashboard_page["Dashboard page<br/>[DashboardPage.tsx]"]
  node_dashboard_cards["Dashboard cards"]
  node_dashboard_metrics["Dashboard metrics<br/>[metrics.ts]"]
  node_ingestion_page["Ingestion page<br/>[IngestionPage.tsx]"]
  node_batch_history["Batch history<br/>[BatchHistory.tsx]"]
  node_catalog_upload_ui["Catalog upload UI"]
  node_transactions_page["Transactions page"]
  node_stores_page["Stores page<br/>[StoresPage.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_api["HTTP API"]
  node_api_routes["API routes<br/>[routes.py]"]
  node_models["Domain models<br/>[models.py]"]
end

subgraph group_ingestion["Sales ingestion"]
  node_import_worker["Batch worker<br/>[import_worker.py]"]
  node_csv_parser["CSV parser<br/>[csv_parser.py]"]
  node_sales_importer["Sales importer<br/>[sales_importer.py]"]
  node_sales_rules["Sale return rules<br/>[sales_rules.py]"]
end

subgraph group_reporting["Catalog and reporting"]
  node_store_import["Store catalog import<br/>[store_import.py]"]
  node_analytics["Dashboard analytics<br/>[analytics.py]"]
end

node_browser(("Browser user"))
node_database[("PostgreSQL")]

node_browser -->|"uses"| node_ingestion_page
node_ingestion_page -->|"uploads files"| node_api_client
node_ingestion_page -->|"shows batches"| node_batch_history
node_ingestion_page -->|"offers catalog upload"| node_catalog_upload_ui
node_api_client -->|"sends HTTP requests"| node_api_routes
node_api_routes -->|"schedules imports"| node_import_worker
node_import_worker -->|"parses staged CSV"| node_csv_parser
node_import_worker -->|"processes valid batch"| node_sales_importer
node_sales_importer -->|"validates row rules"| node_sales_rules
node_import_worker -->|"records batch state"| node_models
node_sales_importer -->|"writes transactions"| node_models
node_api_routes -->|"imports catalog"| node_store_import
node_api_routes -->|"requests dashboard data"| node_analytics
node_api_routes -->|"queries domain data"| node_models
node_store_import -->|"upserts stores"| node_models
node_analytics -->|"queries reporting data"| node_models
node_models -->|"maps persisted records"| node_database
node_dashboard_page -->|"loads analytics"| node_api_client
node_dashboard_page -->|"renders"| node_dashboard_cards
node_dashboard_page -->|"uses metrics"| node_dashboard_metrics
node_transactions_page -->|"searches ledger"| node_api_client
node_stores_page -->|"loads stores"| node_api_client
node_batch_history -->|"loads batch records"| node_api_client
node_catalog_upload_ui -->|"submits catalog"| node_api_client

click node_dashboard_page "https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/frontend/vite-project/src/pages/DashboardPage.tsx"
click node_dashboard_cards "https://github.com/arunkumar7070/kjbn-sales_import_dashboard/tree/main/frontend/vite-project/src/components/dashboard"
click node_dashboard_metrics "https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/frontend/vite-project/src/components/dashboard/metrics.ts"
click node_ingestion_page "https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/frontend/vite-project/src/pages/IngestionPage.tsx"
click node_batch_history "https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/frontend/vite-project/src/components/ingestion/BatchHistory.tsx"
click node_catalog_upload_ui "https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/frontend/vite-project/src/components/stores/StoreCatalogUpload.tsx"
click node_transactions_page "https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/frontend/vite-project/src/pages/TransactionsPage.tsx"
click node_stores_page "https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/frontend/vite-project/src/pages/StoresPage.tsx"
click node_api_client "https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/frontend/vite-project/src/api/client.ts"
click node_api_routes "https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/backend/api/routes.py"
click node_import_worker "https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/backend/app/services/import_worker.py"
click node_csv_parser "https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/backend/app/services/csv_parser.py"
click node_sales_importer "https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/backend/app/services/sales_importer.py"
click node_sales_rules "https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/backend/app/services/sales_rules.py"
click node_store_import "https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/backend/app/services/store_import.py"
click node_analytics "https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/backend/app/services/analytics.py"
click node_models "https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/backend/app/models.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_dashboard_page,node_dashboard_cards,node_dashboard_metrics,node_ingestion_page,node_batch_history,node_catalog_upload_ui,node_transactions_page,node_stores_page,node_api_client,node_browser toneBlue
class node_api_routes,node_models,node_database toneAmber
class node_import_worker,node_csv_parser,node_sales_importer,node_sales_rules toneMint
class node_store_import,node_analytics toneRose
```

## Components

### Web application

- [Dashboard page](https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/frontend/vite-project/src/pages/DashboardPage.tsx): `frontend/vite-project/src/pages/DashboardPage.tsx`
- [Dashboard cards](https://github.com/arunkumar7070/kjbn-sales_import_dashboard/tree/main/frontend/vite-project/src/components/dashboard): `frontend/vite-project/src/components/dashboard`
- [Dashboard metrics](https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/frontend/vite-project/src/components/dashboard/metrics.ts): `frontend/vite-project/src/components/dashboard/metrics.ts`
- [Ingestion page](https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/frontend/vite-project/src/pages/IngestionPage.tsx): `frontend/vite-project/src/pages/IngestionPage.tsx`
- [Batch history](https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/frontend/vite-project/src/components/ingestion/BatchHistory.tsx): `frontend/vite-project/src/components/ingestion/BatchHistory.tsx`
- [Catalog upload UI](https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/frontend/vite-project/src/components/stores/StoreCatalogUpload.tsx): `frontend/vite-project/src/components/stores/StoreCatalogUpload.tsx`
- [Transactions page](https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/frontend/vite-project/src/pages/TransactionsPage.tsx): `frontend/vite-project/src/pages/TransactionsPage.tsx`
- [Stores page](https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/frontend/vite-project/src/pages/StoresPage.tsx): `frontend/vite-project/src/pages/StoresPage.tsx`
- [API client](https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/frontend/vite-project/src/api/client.ts): `frontend/vite-project/src/api/client.ts`

### HTTP API

- [API routes](https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/backend/api/routes.py): `backend/api/routes.py`
- [Domain models](https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/backend/app/models.py): `backend/app/models.py`

### Sales ingestion

- [Batch worker](https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/backend/app/services/import_worker.py): `backend/app/services/import_worker.py`
- [CSV parser](https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/backend/app/services/csv_parser.py): `backend/app/services/csv_parser.py`
- [Sales importer](https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/backend/app/services/sales_importer.py): `backend/app/services/sales_importer.py`
- [Sale return rules](https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/backend/app/services/sales_rules.py): `backend/app/services/sales_rules.py`

### Catalog and reporting

- [Store catalog import](https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/backend/app/services/store_import.py): `backend/app/services/store_import.py`
- [Dashboard analytics](https://github.com/arunkumar7070/kjbn-sales_import_dashboard/blob/main/backend/app/services/analytics.py): `backend/app/services/analytics.py`

### Other components

- **Browser user**
- **PostgreSQL**

## Connections

- Browser user → Ingestion page: uses
- Ingestion page → API client: uploads files (evidence: `frontend/vite-project/src/pages/IngestionPage.tsx`)
- Ingestion page → Batch history: shows batches (evidence: `frontend/vite-project/src/pages/IngestionPage.tsx`)
- Ingestion page → Catalog upload UI: offers catalog upload (evidence: `frontend/vite-project/src/pages/IngestionPage.tsx`)
- API client → API routes: sends HTTP requests
- API routes → Batch worker: schedules imports (evidence: `backend/api/routes.py`)
- Batch worker → CSV parser: parses staged CSV (evidence: `backend/app/services/import_worker.py`)
- Batch worker → Sales importer: processes valid batch (evidence: `backend/app/services/import_worker.py`)
- Sales importer → Sale return rules: validates row rules (evidence: `backend/app/services/sales_importer.py`)
- Batch worker → Domain models: records batch state (evidence: `backend/app/services/import_worker.py`)
- Sales importer → Domain models: writes transactions (evidence: `backend/app/services/sales_importer.py`)
- API routes → Store catalog import: imports catalog (evidence: `backend/api/routes.py`)
- API routes → Dashboard analytics: requests dashboard data (evidence: `backend/api/routes.py`)
- API routes → Domain models: queries domain data (evidence: `backend/api/routes.py`)
- Store catalog import → Domain models: upserts stores (evidence: `backend/app/services/store_import.py`)
- Dashboard analytics → Domain models: queries reporting data (evidence: `backend/app/services/analytics.py`)
- Domain models → PostgreSQL: maps persisted records
- Dashboard page → API client: loads analytics (evidence: `frontend/vite-project/src/pages/DashboardPage.tsx`)
- Dashboard page → Dashboard cards: renders (evidence: `frontend/vite-project/src/pages/DashboardPage.tsx`)
- Dashboard page → Dashboard metrics: uses metrics (evidence: `frontend/vite-project/src/pages/DashboardPage.tsx`)
- Transactions page → API client: searches ledger (evidence: `frontend/vite-project/src/pages/TransactionsPage.tsx`)
- Stores page → API client: loads stores (evidence: `frontend/vite-project/src/pages/StoresPage.tsx`)
- Batch history → API client: loads batch records (evidence: `frontend/vite-project/src/components/ingestion/BatchHistory.tsx`)
- Catalog upload UI → API client: submits catalog (evidence: `frontend/vite-project/src/components/stores/StoreCatalogUpload.tsx`)