# inankarim/sales_bi architecture

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

- Interactive diagram: https://gitdiagram.com/inankarim/sales_bi
- Repository: https://github.com/inankarim/sales_bi

## Overview

1. **Overall shape**
   - This is a **single-page, client-first analytics app** for sales reporting.
   - There is **no database, auth, or remote API layer** in the core product path; the entire analytic workflow runs on data loaded from a user-uploaded CSV.

2. **App shell and routing boundary**
   - The app is built with **React 19 + TanStack Start** on top of Vite.
   - `src/routes/__root.tsx` provides the shared HTML/app shell, while `src/routes/index.tsx` is the main entry route that switches between upload mode and dashboard mode.
   - `src/routeTree.gen.ts` is generated routing metadata, so routing is framework-managed rather than hand-authored.

3. **Primary user flow**
   - The central flow is: **upload CSV → validate → parse → hold rows in route state → derive analytics → render dashboard**.
   - `UploadScreen.tsx` owns the intake experience, including drag-and-drop and schema validation.
   - Once a valid file is accepted, the app transitions to the dashboard without leaving the client.

4. **CSV parsing and schema enforcement**
   - `src/lib/sales-data.ts` is the key data boundary for ingestion.
   - It parses CSV input into a structured sales row model and enforces the required header schema:
     `Region, Area, Territory, Customer Name, PLC, PLC+, POW, Holcim SS, HWP, HCG`.
   - Extra columns are ignored; missing required columns trigger the invalid-template error shown in the README.

5. **State ownership and data derivation**
   - `routes/index.tsx` appears to own the uploaded dataset state and pass it down into the dashboard layer.
   - `Dashboard.tsx` is the main orchestration component: it applies filters, computes derived datasets, and feeds the visual subcomponents.
   - This keeps raw data handling above the chart/UI layer and derived analytics below it.

6. **Filtering and exploration subsystem**
   - `FilterBar.tsx` provides hierarchical slicing by **Region → Area → Territory**, plus customer/product search.
   - These filters are the main control plane for the dashboard and directly affect every KPI, chart, and drill-down view.
   - The filtering model is the main “business logic” boundary in the UI.

7. **Analytics and presentation layer**
   - `KpiCard.tsx`, `InsightsPanel.tsx`, and `CustomerExplorer.tsx` consume derived data and present it in different forms:
     - KPI summaries for top-level metrics
     - auto-generated executive insights
     - customer-level drill-down tables/details
   - These components do not appear to own data; they are renderers over computed slices.

8. **Visualization subsystem**
   - The charts are rendered with **Recharts** and appear to include:
     - region bars
     - product mix views
     - region × product heatmap
     - area stacked bars
     - territory ranking bars and treemap
   - `src/components/ui/chart.tsx` and related primitives support the charting layer, while the dashboard components assemble the actual views.

9. **Export and capture capabilities**
   - The app supports two export paths described in the README:
     - **filtered CSV export**
     - **PNG export of individual charts**
   - This implies a secondary data-output boundary separate from the display path, using browser-side generation rather than backend jobs.
   - `html-to-image` is the notable technology enabling chart screenshots.

10. **UI system and design foundation**
   - The UI is built with **Tailwind CSS v4** plus a large set of **shadcn/ui** primitives under `src/components/ui`.
   - These primitives form the reusable interaction layer for buttons, dialogs, tables, tabs, dropdowns, popovers, etc.
   - `src/styles.css` likely defines the global theme/tokens, while `src/lib/utils.ts` supports class composition and UI helpers.

11. **Platform/runtime boundary**
   - `src/start.ts`, `src/server.ts`, and `wrangler.jsonc` indicate the app is packaged with a framework/runtime layer suitable for deployment on a managed edge/server platform, but the product itself remains data-local and browser-driven.
   - The server side is infrastructural rather than domain-heavy; the sales intelligence logic stays in the client.

12. **Error and responsiveness support**
   - `src/lib/error-capture.ts` and `src/lib/error-page.ts` suggest centralized error handling for runtime failures and invalid data states.
   - `src/hooks/use-mobile.tsx` indicates responsive behavior, likely used to adjust layout for smaller screens.
   - Together, these support a polished dashboard experience without changing the core data flow.

13. **What to draw in an architecture diagram**
   - The main boxes should be: **Upload UI**, **CSV parser/validator**, **route-level dataset state**, **filter/aggregation logic**, **dashboard visualizations**, and **export/capture utilities**.
   - The key boundary is between **raw uploaded CSV** and **derived analytics views**; everything after parsing is computed in-browser from the same loaded dataset.

Main entry points: [`src/components/dashboard/Dashboard.tsx`](https://github.com/inankarim/sales_bi/blob/main/src/components/dashboard/Dashboard.tsx) (Dashboard), [`src/routes/index.tsx`](https://github.com/inankarim/sales_bi/blob/main/src/routes/index.tsx) (Entry route), [`src/router.tsx`](https://github.com/inankarim/sales_bi/blob/main/src/router.tsx) (router), [`src/routes/__root.tsx`](https://github.com/inankarim/sales_bi/blob/main/src/routes/__root.tsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime shell"]
  node_src_start["start<br/>client bootstrap<br/>[start.ts]"]
  node_src_server["server<br/>edge runtime<br/>[server.ts]"]
  node_src_router["router<br/>[router.tsx]"]
  node_root_route["App shell<br/>root route<br/>[__root.tsx]"]
  node_route_tree["Route tree<br/>generated metadata<br/>[routeTree.gen.ts]"]
end

subgraph group_ingest["Data intake"]
  node_index_route["Entry route<br/>route controller<br/>[index.tsx]"]
  node_upload_screen["Upload screen<br/>upload UI<br/>[UploadScreen.tsx]"]
  node_sales_data["Sales parser<br/>csv schema<br/>[sales-data.ts]"]
end

subgraph group_analytics["Analytics UI"]
  node_dashboard["Dashboard<br/>orchestrator<br/>[Dashboard.tsx]"]
  node_filter_bar["Filter bar<br/>filtering control<br/>[FilterBar.tsx]"]
  node_kpi_card["KPI cards<br/>metric view<br/>[KpiCard.tsx]"]
  node_insights_panel["Insights panel<br/>insight view<br/>[InsightsPanel.tsx]"]
  node_customer_explorer["Customer explorer<br/>drill-down view"]
end

subgraph group_ui["UI system"]
  node_chart_ui["Chart primitives<br/>recharts support<br/>[chart.tsx]"]
  node_ui_primitives["UI primitives<br/>design system<br/>[button.tsx]"]
  node_error_support["Error support<br/>error handling<br/>[error-capture.ts]"]
  node_mobile_hook["Mobile hook<br/>responsive hook<br/>[use-mobile.tsx]"]
  node_styles["Global styles<br/>theme stylesheet<br/>[styles.css]"]
end

node_src_start -->|"mounts"| node_src_router
node_src_server -->|"serves"| node_src_router
node_src_router -->|"contains"| node_root_route
node_src_router -->|"uses"| node_route_tree
node_root_route -->|"hosts"| node_index_route
node_index_route -->|"shows upload"| node_upload_screen
node_index_route -->|"shows dashboard"| node_dashboard
node_upload_screen -->|"validates"| node_sales_data
node_index_route -->|"stores rows"| node_sales_data
node_dashboard -->|"coordinates"| node_filter_bar
node_dashboard -->|"feeds"| node_kpi_card
node_dashboard -->|"feeds"| node_insights_panel
node_dashboard -->|"feeds"| node_customer_explorer
node_dashboard -->|"renders charts"| node_chart_ui
node_dashboard -->|"uses controls"| node_ui_primitives
node_upload_screen -->|"uses controls"| node_ui_primitives
node_chart_ui -->|"composes"| node_ui_primitives
node_error_support -->|"wraps"| node_root_route
node_mobile_hook -->|"adapts layout"| node_dashboard
node_styles -->|"themes"| node_root_route

click node_src_start "https://github.com/inankarim/sales_bi/blob/main/src/start.ts"
click node_src_server "https://github.com/inankarim/sales_bi/blob/main/src/server.ts"
click node_src_router "https://github.com/inankarim/sales_bi/blob/main/src/router.tsx"
click node_root_route "https://github.com/inankarim/sales_bi/blob/main/src/routes/__root.tsx"
click node_index_route "https://github.com/inankarim/sales_bi/blob/main/src/routes/index.tsx"
click node_route_tree "https://github.com/inankarim/sales_bi/blob/main/src/routeTree.gen.ts"
click node_upload_screen "https://github.com/inankarim/sales_bi/blob/main/src/components/dashboard/UploadScreen.tsx"
click node_sales_data "https://github.com/inankarim/sales_bi/blob/main/src/lib/sales-data.ts"
click node_dashboard "https://github.com/inankarim/sales_bi/blob/main/src/components/dashboard/Dashboard.tsx"
click node_filter_bar "https://github.com/inankarim/sales_bi/blob/main/src/components/dashboard/FilterBar.tsx"
click node_kpi_card "https://github.com/inankarim/sales_bi/blob/main/src/components/dashboard/KpiCard.tsx"
click node_insights_panel "https://github.com/inankarim/sales_bi/blob/main/src/components/dashboard/InsightsPanel.tsx"
click node_customer_explorer "https://github.com/inankarim/sales_bi/blob/main/src/components/dashboard/CustomerExplorer.tsx"
click node_chart_ui "https://github.com/inankarim/sales_bi/blob/main/src/components/ui/chart.tsx"
click node_ui_primitives "https://github.com/inankarim/sales_bi/blob/main/src/components/ui/button.tsx"
click node_error_support "https://github.com/inankarim/sales_bi/blob/main/src/lib/error-capture.ts"
click node_mobile_hook "https://github.com/inankarim/sales_bi/blob/main/src/hooks/use-mobile.tsx"
click node_styles "https://github.com/inankarim/sales_bi/blob/main/src/styles.css"

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_src_start,node_src_server,node_src_router,node_root_route,node_route_tree toneBlue
class node_index_route,node_upload_screen,node_sales_data toneAmber
class node_dashboard,node_filter_bar,node_kpi_card,node_insights_panel,node_customer_explorer toneMint
class node_chart_ui,node_ui_primitives,node_error_support,node_mobile_hook,node_styles toneRose
```

## Components

### Runtime shell

Framework entry, routing, and deployment boundary.

- [start](https://github.com/inankarim/sales_bi/blob/main/src/start.ts): client bootstrap · Client entry that mounts the app. · `src/start.ts`
- [server](https://github.com/inankarim/sales_bi/blob/main/src/server.ts): edge runtime · Server/runtime wrapper for deployment. · `src/server.ts`
- [router](https://github.com/inankarim/sales_bi/blob/main/src/router.tsx): tanstack router · Router setup for the application shell. · `src/router.tsx`
- [App shell](https://github.com/inankarim/sales_bi/blob/main/src/routes/__root.tsx): root route · Shared HTML and app shell boundary. · `src/routes/__root.tsx`
- [Route tree](https://github.com/inankarim/sales_bi/blob/main/src/routeTree.gen.ts): generated metadata · Framework-generated routing metadata. · `src/routeTree.gen.ts`

### Data intake

CSV upload, validation, and route-owned dataset state.

- [Entry route](https://github.com/inankarim/sales_bi/blob/main/src/routes/index.tsx): route controller · Main route that switches between upload and dashboard modes. · `src/routes/index.tsx`
- [Upload screen](https://github.com/inankarim/sales_bi/blob/main/src/components/dashboard/UploadScreen.tsx): upload UI · Drag-and-drop intake and template validation. · `src/components/dashboard/UploadScreen.tsx`
- [Sales parser](https://github.com/inankarim/sales_bi/blob/main/src/lib/sales-data.ts): csv schema · Parses CSV rows and enforces the sales header schema. · `src/lib/sales-data.ts`

### Analytics UI

Dashboard orchestration, filtering, and presentation components.

- [Dashboard](https://github.com/inankarim/sales_bi/blob/main/src/components/dashboard/Dashboard.tsx): orchestrator · Coordinates filters, derived data, and dashboard sections. · `src/components/dashboard/Dashboard.tsx`
- [Filter bar](https://github.com/inankarim/sales_bi/blob/main/src/components/dashboard/FilterBar.tsx): filtering control · Region, area, territory, and search controls. · `src/components/dashboard/FilterBar.tsx`
- [KPI cards](https://github.com/inankarim/sales_bi/blob/main/src/components/dashboard/KpiCard.tsx): metric view · Top-level summary metric tiles. · `src/components/dashboard/KpiCard.tsx`
- [Insights panel](https://github.com/inankarim/sales_bi/blob/main/src/components/dashboard/InsightsPanel.tsx): insight view · Auto-generated executive insights display. · `src/components/dashboard/InsightsPanel.tsx`
- [Customer explorer](https://github.com/inankarim/sales_bi/blob/main/src/components/dashboard/CustomerExplorer.tsx): drill-down view · Customer-level table and detail exploration. · `src/components/dashboard/CustomerExplorer.tsx`

### UI system

Reusable design system, chart primitives, responsiveness, and error handling.

- [Chart primitives](https://github.com/inankarim/sales_bi/blob/main/src/components/ui/chart.tsx): recharts support · Shared chart wrapper and composition helpers. · `src/components/ui/chart.tsx`
- [UI primitives](https://github.com/inankarim/sales_bi/blob/main/src/components/ui/button.tsx): design system · Reusable shadcn-style controls and layout building blocks. · `src/components/ui/button.tsx`
- [Error support](https://github.com/inankarim/sales_bi/blob/main/src/lib/error-capture.ts): error handling · Centralized error capture and error page rendering. · `src/lib/error-capture.ts`
- [Mobile hook](https://github.com/inankarim/sales_bi/blob/main/src/hooks/use-mobile.tsx): responsive hook · Responsive breakpoint helper for small screens. · `src/hooks/use-mobile.tsx`
- [Global styles](https://github.com/inankarim/sales_bi/blob/main/src/styles.css): theme stylesheet · Global Tailwind/theme tokens and app-wide styling. · `src/styles.css`

## Connections

- start → router: mounts · Bootstraps the application through the router.
- server → router: serves · Provides the runtime context for the routed app.
- router → App shell: contains · Declares the root shell boundary.
- router → Route tree: uses · Consumes generated route metadata.
- App shell → Entry route: hosts · Renders the main application route.
- Entry route → Upload screen: shows upload · Presents intake when no dataset is loaded.
- Entry route → Dashboard: shows dashboard · Presents analytics once valid CSV data is accepted.
- Upload screen → Sales parser: validates · Uses the sales schema and CSV parsing boundary.
- Entry route → Sales parser: stores rows · Holds parsed rows in route-level state.
- Dashboard → Filter bar: coordinates · Applies filtering controls to all analytics views.
- Dashboard → KPI cards: feeds · Supplies derived KPI summaries.
- Dashboard → Insights panel: feeds · Supplies computed insights.
- Dashboard → Customer explorer: feeds · Supplies filtered customer drill-down data.
- Dashboard → Chart primitives: renders charts · Uses shared chart primitives for visualizations.
- Dashboard → UI primitives: uses controls · Builds the dashboard UI from reusable components.
- Upload screen → UI primitives: uses controls · Builds the upload experience from reusable components.
- Chart primitives → UI primitives: composes · Chart wrapper depends on common UI building blocks.
- Error support → App shell: wraps · Supports centralized runtime and invalid-state handling.
- Mobile hook → Dashboard: adapts layout · Supports responsive dashboard behavior.
- Global styles → App shell: themes · Provides global styling for the app shell.
