# ag15082004/e-commerce architecture

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

- Interactive diagram: https://gitdiagram.com/ag15082004/e-commerce
- Repository: https://github.com/ag15082004/e-commerce

## Overview

#### Purpose and runtime
A Vite React/TypeScript analytics dashboard with multiple business-analysis views and an embedded “Genie” conversational analytics capability. The repository also contains a TypeScript server layer intended to route LLM-driven requests, generate/validate SQL, query Databricks, and return insights or charts.

Client bootstrap is `src/main.tsx`; the root UI is `src/App.tsx`. The server entry point is `server.ts`.

#### Application shell and navigation
The shared application frame separates navigation and page presentation from analytics content:
- `src/components/layout/Layout.tsx`
- `src/components/layout/Navbar.tsx`
- `src/components/layout/Sidebar.tsx`
- `src/components/layout/PageHeader.tsx`

`App.tsx` is expected to compose this layout and select the analytical page. Shared empty/loading/error states establish UI boundaries for asynchronous analytics and failures:
- `src/components/common/LoadingState.tsx`
- `src/components/common/ErrorBoundary.tsx`
- `src/components/common/EmptyState.tsx`

#### Analytics page layer
Business domains are represented as distinct React page modules, providing the dashboard’s primary presentation boundary:
- `src/pages/ExecutiveDashboard.tsx`
- `src/pages/SalesAnalytics.tsx`
- `src/pages/CustomerAnalytics.tsx`
- `src/pages/DeliveryAnalytics.tsx`
- `src/pages/MarketingAnalytics.tsx`
- `src/pages/ProductPerformance.tsx`
- `src/pages/SupportClickstream.tsx`
- `src/pages/PredictiveAnalytics.tsx`

These pages consume common analytics-oriented state and utilities rather than directly owning infrastructure access.

#### Client analytics and data adapters
React hooks encapsulate client-side analytics retrieval/processing and predictive-analysis behavior:
- `src/hooks/useAnalytics.tsx`
- `src/hooks/usePredictiveAnalytics.tsx`

The client service boundary is `src/services/api.ts`. Domain calculation and external-system adaptation are isolated in:
- `src/utils/analyticsEngine.ts`
- `src/utils/databricksAdapter.ts`
- `src/utils/mlAdapter.ts`

This division allows pages to render structured analytics while adapters hide Databricks and ML integration details. `src/utils/export.ts` supports exporting produced analytics.

#### Conversational analytics entry point
`src/components/common/GenieChat.tsx` is the UI boundary for natural-language analytics requests. It should send requests through the client API layer rather than access models or Databricks directly:
- `src/components/common/GenieChat.tsx`
- `src/services/api.ts`
- `src/server/controllers/genieController.ts`

The controller is the server-side request boundary and delegates orchestration rather than embedding provider logic.

#### Genie agent pipeline
The backend service graph implements an LLM-to-data workflow:
- `src/server/services/agentRouter.ts` classifies/routes requests.
- `src/server/services/conversationManager.ts` preserves multi-turn context.
- `src/server/services/promptBuilder.ts` constructs model prompts.
- `src/server/services/llmService.ts` invokes the LLM.
- `src/server/services/sqlGenerator.ts` derives query text.
- `src/server/services/sqlValidator.ts` constrains generated SQL before execution.
- `src/server/services/databricksConnector.ts` executes approved queries against Databricks.
- `src/server/services/insightGenerator.ts` and `src/server/services/chartGenerator.ts` convert returned data into narrative/chart-ready output.

The critical trust boundary is between LLM-generated SQL and `databricksConnector.ts`; validation must precede execution.

#### Infrastructure and UI foundation
The client runs in the browser via Vite (`vite.config.ts`) and is styled with Tailwind/PostCSS:
- `tailwind.config.js`
- `postcss.config.js`
- `src/index.css`

Reusable UI primitives under `src/components/ui/` provide consistent controls and tables. The material external dependencies implied by the architecture are an LLM provider, Databricks, and an ML/predictive analytics backend or adapter.

Main entry points: [`src/server/controllers/genieController.ts`](https://github.com/ag15082004/e-commerce/blob/main/src/server/controllers/genieController.ts) (Genie controller), [`src/components/layout/Layout.tsx`](https://github.com/ag15082004/e-commerce/blob/main/src/components/layout/Layout.tsx) (Application shell), [`src/hooks/useAnalytics.tsx`](https://github.com/ag15082004/e-commerce/blob/main/src/hooks/useAnalytics.tsx) (Analytics hooks), [`src/server/services/llmService.ts`](https://github.com/ag15082004/e-commerce/blob/main/src/server/services/llmService.ts) (LLM service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React Client"]
  node_vite{{"Vite browser runtime<br/>[vite.config.ts]"}}
  node_app["App root<br/>React root<br/>[App.tsx]"]
  node_layout["Application shell<br/>layout<br/>[Layout.tsx]"]
  node_pages["Business analytics pages<br/>page modules"]
  node_ui["UI primitives<br/>component library"]
  node_states["Async UI states<br/>shared components<br/>[LoadingState.tsx]"]
  node_genie_chat["Genie Chat<br/>conversational UI<br/>[GenieChat.tsx]"]
end

subgraph group_analytics["Client Analytics"]
  node_hooks["Analytics hooks<br/>React hooks<br/>[useAnalytics.tsx]"]
  node_client_api["Client API<br/>service boundary<br/>[api.ts]"]
  node_analytics_engine["Analytics engine<br/>domain calculations<br/>[analyticsEngine.ts]"]
  node_adapters["Data and ML adapters<br/>integration adapters"]
end

subgraph group_server["Genie Server"]
  node_server_entry{{"Server entry<br/>server runtime<br/>[server.ts]"}}
  node_genie_controller["Genie controller<br/>request controller<br/>[genieController.ts]"]
  node_agent_router["Agent router<br/>request routing<br/>[agentRouter.ts]"]
  node_conversation["Conversation manager<br/>context service"]
  node_prompt_builder["Prompt builder<br/>prompt service<br/>[promptBuilder.ts]"]
  node_llm["LLM service<br/>model gateway<br/>[llmService.ts]"]
  node_sql_generator["SQL generator<br/>query generation<br/>[sqlGenerator.ts]"]
  node_sql_validator["SQL validator<br/>trust boundary<br/>[sqlValidator.ts]"]
  node_databricks_connector["Databricks connector<br/>query execution"]
  node_insight_output["Insight and chart output<br/>result generation"]
end

subgraph group_external["External Systems"]
  node_llm_provider(("LLM provider<br/>external model"))
  node_databricks[("Databricks<br/>data platform")]
  node_ml_backend(("ML backend<br/>predictive analytics"))
end

node_vite -->|"boots"| node_app
node_app -->|"composes"| node_layout
node_layout -->|"presents"| node_pages
node_layout -->|"uses"| node_ui
node_pages -->|"shows async states"| node_states
node_pages -->|"uses"| node_hooks
node_hooks -->|"retrieves via"| node_client_api
node_hooks -->|"processes with"| node_analytics_engine
node_analytics_engine -->|"integrates through"| node_adapters
node_adapters -.->|"adapts"| node_databricks
node_adapters -.->|"adapts"| node_ml_backend
node_genie_chat -->|"sends requests"| node_client_api
node_client_api -->|"calls"| node_genie_controller
node_server_entry -->|"routes requests"| node_genie_controller
node_genie_controller -->|"delegates"| node_agent_router
node_agent_router -->|"loads context"| node_conversation
node_conversation -->|"supplies context"| node_prompt_builder
node_prompt_builder -->|"builds request"| node_llm
node_llm -->|"invokes"| node_llm_provider
node_llm -->|"drives query derivation"| node_sql_generator
node_sql_generator -->|"generated SQL"| node_sql_validator
node_sql_validator -->|"approved SQL only"| node_databricks_connector
node_databricks_connector -->|"executes"| node_databricks
node_databricks_connector -->|"query results"| node_insight_output
node_insight_output -->|"response"| node_genie_controller

click node_vite "https://github.com/ag15082004/e-commerce/blob/main/vite.config.ts"
click node_app "https://github.com/ag15082004/e-commerce/blob/main/src/App.tsx"
click node_layout "https://github.com/ag15082004/e-commerce/blob/main/src/components/layout/Layout.tsx"
click node_states "https://github.com/ag15082004/e-commerce/blob/main/src/components/common/LoadingState.tsx"
click node_genie_chat "https://github.com/ag15082004/e-commerce/blob/main/src/components/common/GenieChat.tsx"
click node_hooks "https://github.com/ag15082004/e-commerce/blob/main/src/hooks/useAnalytics.tsx"
click node_client_api "https://github.com/ag15082004/e-commerce/blob/main/src/services/api.ts"
click node_analytics_engine "https://github.com/ag15082004/e-commerce/blob/main/src/utils/analyticsEngine.ts"
click node_server_entry "https://github.com/ag15082004/e-commerce/blob/main/server.ts"
click node_genie_controller "https://github.com/ag15082004/e-commerce/blob/main/src/server/controllers/genieController.ts"
click node_agent_router "https://github.com/ag15082004/e-commerce/blob/main/src/server/services/agentRouter.ts"
click node_conversation "https://github.com/ag15082004/e-commerce/blob/main/src/server/services/conversationManager.ts"
click node_prompt_builder "https://github.com/ag15082004/e-commerce/blob/main/src/server/services/promptBuilder.ts"
click node_llm "https://github.com/ag15082004/e-commerce/blob/main/src/server/services/llmService.ts"
click node_sql_generator "https://github.com/ag15082004/e-commerce/blob/main/src/server/services/sqlGenerator.ts"
click node_sql_validator "https://github.com/ag15082004/e-commerce/blob/main/src/server/services/sqlValidator.ts"
click node_databricks_connector "https://github.com/ag15082004/e-commerce/blob/main/src/server/services/databricksConnector.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_vite,node_app,node_layout,node_pages,node_ui,node_states,node_genie_chat toneBlue
class node_hooks,node_client_api,node_analytics_engine,node_adapters toneAmber
class node_server_entry,node_genie_controller,node_agent_router,node_conversation,node_prompt_builder,node_llm,node_sql_generator,node_sql_validator,node_databricks_connector,node_insight_output toneMint
class node_llm_provider,node_databricks,node_ml_backend toneRose
```

## Components

### React Client

Browser dashboard and shared presentation layers.

- [Vite browser runtime](https://github.com/ag15082004/e-commerce/blob/main/vite.config.ts): runtime · `vite.config.ts`
- [App root](https://github.com/ag15082004/e-commerce/blob/main/src/App.tsx): React root · `src/App.tsx`
- [Application shell](https://github.com/ag15082004/e-commerce/blob/main/src/components/layout/Layout.tsx): layout · Navigation and page presentation frame. · `src/components/layout/Layout.tsx`
- **Business analytics pages**: page modules · Executive, sales, customer, delivery, marketing, product, support, and predictive views.
- **UI primitives**: component library
- [Async UI states](https://github.com/ag15082004/e-commerce/blob/main/src/components/common/LoadingState.tsx): shared components · Loading, empty, and error boundaries. · `src/components/common/LoadingState.tsx`
- [Genie Chat](https://github.com/ag15082004/e-commerce/blob/main/src/components/common/GenieChat.tsx): conversational UI · `src/components/common/GenieChat.tsx`

### Client Analytics

Client-side retrieval, processing, and integration adapters.

- [Analytics hooks](https://github.com/ag15082004/e-commerce/blob/main/src/hooks/useAnalytics.tsx): React hooks · Analytics retrieval and predictive behavior. · `src/hooks/useAnalytics.tsx`
- [Client API](https://github.com/ag15082004/e-commerce/blob/main/src/services/api.ts): service boundary · `src/services/api.ts`
- [Analytics engine](https://github.com/ag15082004/e-commerce/blob/main/src/utils/analyticsEngine.ts): domain calculations · `src/utils/analyticsEngine.ts`
- **Data and ML adapters**: integration adapters · Hides Databricks and ML integration details.

### Genie Server

Conversational analytics request and query pipeline.

- [Server entry](https://github.com/ag15082004/e-commerce/blob/main/server.ts): server runtime · `server.ts`
- [Genie controller](https://github.com/ag15082004/e-commerce/blob/main/src/server/controllers/genieController.ts): request controller · `src/server/controllers/genieController.ts`
- [Agent router](https://github.com/ag15082004/e-commerce/blob/main/src/server/services/agentRouter.ts): request routing · `src/server/services/agentRouter.ts`
- [Conversation manager](https://github.com/ag15082004/e-commerce/blob/main/src/server/services/conversationManager.ts): context service · Preserves multi-turn context. · `src/server/services/conversationManager.ts`
- [Prompt builder](https://github.com/ag15082004/e-commerce/blob/main/src/server/services/promptBuilder.ts): prompt service · `src/server/services/promptBuilder.ts`
- [LLM service](https://github.com/ag15082004/e-commerce/blob/main/src/server/services/llmService.ts): model gateway · `src/server/services/llmService.ts`
- [SQL generator](https://github.com/ag15082004/e-commerce/blob/main/src/server/services/sqlGenerator.ts): query generation · `src/server/services/sqlGenerator.ts`
- [SQL validator](https://github.com/ag15082004/e-commerce/blob/main/src/server/services/sqlValidator.ts): trust boundary · Constrains generated SQL before execution. · `src/server/services/sqlValidator.ts`
- [Databricks connector](https://github.com/ag15082004/e-commerce/blob/main/src/server/services/databricksConnector.ts): query execution · `src/server/services/databricksConnector.ts`
- **Insight and chart output**: result generation · Converts query results to narrative and chart-ready output.

### External Systems

- **LLM provider**: external model
- **Databricks**: data platform
- **ML backend**: predictive analytics

## Connections

- Vite browser runtime → App root: boots
- App root → Application shell: composes
- Application shell → Business analytics pages: presents
- Application shell → UI primitives: uses
- Business analytics pages → Async UI states: shows async states
- Business analytics pages → Analytics hooks: uses
- Analytics hooks → Client API: retrieves via
- Analytics hooks → Analytics engine: processes with
- Analytics engine → Data and ML adapters: integrates through
- Data and ML adapters → Databricks: adapts
- Data and ML adapters → ML backend: adapts
- Genie Chat → Client API: sends requests
- Client API → Genie controller: calls
- Server entry → Genie controller: routes requests
- Genie controller → Agent router: delegates
- Agent router → Conversation manager: loads context
- Conversation manager → Prompt builder: supplies context
- Prompt builder → LLM service: builds request
- LLM service → LLM provider: invokes
- LLM service → SQL generator: drives query derivation
- SQL generator → SQL validator: generated SQL
- SQL validator → Databricks connector: approved SQL only
- Databricks connector → Databricks: executes
- Databricks connector → Insight and chart output: query results
- Insight and chart output → Genie controller: response