How inankarim/sales_bi works
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: Dashboard.tsx Dashboard · index.tsx Entry route · router.tsx router · __root.tsx App shell
Components 18
Runtime shell
Framework entry, routing, and deployment boundary.
- start · Client entry that mounts the app.
src/start.ts - server · Server/runtime wrapper for deployment.
src/server.ts - router · Router setup for the application shell.
src/router.tsx - App shell · Shared HTML and app shell boundary.
src/routes/__root.tsx - Route tree · Framework-generated routing metadata.
src/routeTree.gen.ts
Data intake
CSV upload, validation, and route-owned dataset state.
- Entry route · Main route that switches between upload and dashboard modes.
src/routes/index.tsx - Upload screen · Drag-and-drop intake and template validation.
src/components/dashboard/UploadScreen.tsx - Sales parser · Parses CSV rows and enforces the sales header schema.
src/lib/sales-data.ts
Analytics UI
Dashboard orchestration, filtering, and presentation components.
- Dashboard · Coordinates filters, derived data, and dashboard sections.
src/components/dashboard/Dashboard.tsx - Filter bar · Region, area, territory, and search controls.
src/components/dashboard/FilterBar.tsx - KPI cards · Top-level summary metric tiles.
src/components/dashboard/KpiCard.tsx - Insights panel · Auto-generated executive insights display.
src/components/dashboard/InsightsPanel.tsx - Customer explorer · Customer-level table and detail exploration.
src/components/dashboard/CustomerExplorer.tsx
UI system
Reusable design system, chart primitives, responsiveness, and error handling.
- Chart primitives · Shared chart wrapper and composition helpers.
src/components/ui/chart.tsx - UI primitives · Reusable shadcn-style controls and layout building blocks.
src/components/ui/button.tsx - Error support · Centralized error capture and error page rendering.
src/lib/error-capture.ts - Mobile hook · Responsive breakpoint helper for small screens.
src/hooks/use-mobile.tsx - Global styles · Global Tailwind/theme tokens and app-wide styling.
src/styles.css
Connections 20
- 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.