# karan8989-ux/neemans-ai architecture

> Architecture diagram of the GitHub repository karan8989-ux/neemans-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/karan8989-ux/neemans-ai
- Repository: https://github.com/karan8989-ux/neemans-ai

## Overview

Neeman’s AI Business Intelligence is a React dashboard backed by FastAPI and pandas analytics. Users view business KPIs and AI highlights, generate a daily briefing, explore customer feedback, ask the analytics-grounded Copilot questions, or upload and reset CSV datasets. Uploaded CSVs are mapped and validated before replacing in-memory data; analytics then supplies dashboard and AI features. The README identifies `backend/` as active and the nested backend as an older duplicate, so the duplicate is omitted. Some frontend-to-API links are documented rather than visible in sampled page code.

Main entry points: [`backend/main.py`](https://github.com/karan8989-ux/neemans-ai/blob/master/backend/main.py) (FastAPI app), [`backend/services/analytics.py`](https://github.com/karan8989-ux/neemans-ai/blob/master/backend/services/analytics.py) (Pandas analytics), [`frontend/src/App.tsx`](https://github.com/karan8989-ux/neemans-ai/blob/master/frontend/src/App.tsx) (Page router), [`frontend/src/services/api.ts`](https://github.com/karan8989-ux/neemans-ai/blob/master/frontend/src/services/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dashboard"]
  node_app["Page router<br/>[App.tsx]"]
  node_overview_page["Business overview<br/>[OverviewPage.tsx]"]
  node_briefing_page["Daily briefing<br/>[BriefingPage.tsx]"]
  node_feedback_page["Feedback explorer<br/>[FeedbackPage.tsx]"]
  node_sources_page["Data sources"]
  node_copilot_ui["Copilot chat"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API routes"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_overview_route["Overview routes<br/>[overview.py]"]
  node_briefing_route["Briefing routes<br/>[briefing.py]"]
  node_feedback_route["Feedback routes<br/>[feedback.py]"]
  node_upload_route["Upload routes<br/>[upload.py]"]
  node_copilot_route["Copilot routes<br/>[copilot.py]"]
end

subgraph group_data["Data and analytics"]
  node_schema_mapper["CSV mapping<br/>[schema_mapper.py]"]
  node_store[("Dataset store<br/>[data_store.py]")]
  node_analytics["Pandas analytics<br/>[analytics.py]"]
end

subgraph group_ai["AI insights"]
  node_overview_agent["Overview insights<br/>[overview_agent.py]"]
  node_briefing_agent["Briefing generator<br/>[briefing_agent.py]"]
  node_feedback_agent["Feedback recommendations<br/>[feedback_agent.py]"]
  node_copilot_agent["Copilot agent<br/>[copilot_agent.py]"]
end

node_user(("Business user"))
node_claude{{"Anthropic Claude"}}

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_overview_page
node_app -->|"routes to"| node_briefing_page
node_app -->|"routes to"| node_feedback_page
node_app -->|"routes to"| node_sources_page
node_app -->|"renders"| node_copilot_ui
node_overview_page -.->|"requests data"| node_api_client
node_briefing_page -.->|"requests data"| node_api_client
node_feedback_page -.->|"requests data"| node_api_client
node_sources_page -.->|"uploads CSVs"| node_api_client
node_copilot_ui -.->|"asks questions"| node_api_client
node_api_client -->|"calls API"| node_api_app
node_api_app -->|"registers"| node_overview_route
node_api_app -->|"registers"| node_briefing_route
node_api_app -->|"registers"| node_feedback_route
node_api_app -->|"registers"| node_upload_route
node_api_app -->|"registers"| node_copilot_route
node_api_app -->|"loads demo data"| node_store
node_upload_route -->|"validates CSV"| node_schema_mapper
node_upload_route -->|"replaces dataset"| node_store
node_schema_mapper -.->|"maps ambiguous columns"| node_claude
node_overview_route -->|"reads aggregates"| node_analytics
node_briefing_route -->|"reads aggregates"| node_analytics
node_feedback_route -->|"reads feedback"| node_analytics
node_copilot_route -->|"dispatches chat"| node_copilot_agent
node_analytics -->|"reads datasets"| node_store
node_overview_route -->|"requests highlights"| node_overview_agent
node_briefing_route -->|"generates briefing"| node_briefing_agent
node_feedback_route -->|"requests recommendations"| node_feedback_agent
node_overview_agent -->|"uses aggregates"| node_analytics
node_briefing_agent -->|"uses aggregates"| node_analytics
node_feedback_agent -->|"uses aggregates"| node_analytics
node_copilot_agent -->|"gathers context"| node_analytics
node_overview_agent -.->|"generates insights"| node_claude
node_briefing_agent -.->|"generates briefing"| node_claude
node_feedback_agent -->|"generates recommendations"| node_claude
node_copilot_agent -->|"generates answer"| node_claude

click node_app "https://github.com/karan8989-ux/neemans-ai/blob/master/frontend/src/App.tsx"
click node_overview_page "https://github.com/karan8989-ux/neemans-ai/blob/master/frontend/src/pages/OverviewPage.tsx"
click node_briefing_page "https://github.com/karan8989-ux/neemans-ai/blob/master/frontend/src/pages/BriefingPage.tsx"
click node_feedback_page "https://github.com/karan8989-ux/neemans-ai/blob/master/frontend/src/pages/FeedbackPage.tsx"
click node_sources_page "https://github.com/karan8989-ux/neemans-ai/blob/master/frontend/src/pages/DataSourcesPage.tsx"
click node_copilot_ui "https://github.com/karan8989-ux/neemans-ai/blob/master/frontend/src/components/copilot/AIBusinessCopilot.tsx"
click node_api_client "https://github.com/karan8989-ux/neemans-ai/blob/master/frontend/src/services/api.ts"
click node_api_app "https://github.com/karan8989-ux/neemans-ai/blob/master/backend/main.py"
click node_overview_route "https://github.com/karan8989-ux/neemans-ai/blob/master/backend/routers/overview.py"
click node_briefing_route "https://github.com/karan8989-ux/neemans-ai/blob/master/backend/routers/briefing.py"
click node_feedback_route "https://github.com/karan8989-ux/neemans-ai/blob/master/backend/routers/feedback.py"
click node_upload_route "https://github.com/karan8989-ux/neemans-ai/blob/master/backend/routers/upload.py"
click node_copilot_route "https://github.com/karan8989-ux/neemans-ai/blob/master/backend/routers/copilot.py"
click node_schema_mapper "https://github.com/karan8989-ux/neemans-ai/blob/master/backend/services/schema_mapper.py"
click node_store "https://github.com/karan8989-ux/neemans-ai/blob/master/backend/services/data_store.py"
click node_analytics "https://github.com/karan8989-ux/neemans-ai/blob/master/backend/services/analytics.py"
click node_overview_agent "https://github.com/karan8989-ux/neemans-ai/blob/master/backend/agents/overview_agent.py"
click node_briefing_agent "https://github.com/karan8989-ux/neemans-ai/blob/master/backend/agents/briefing_agent.py"
click node_feedback_agent "https://github.com/karan8989-ux/neemans-ai/blob/master/backend/agents/feedback_agent.py"
click node_copilot_agent "https://github.com/karan8989-ux/neemans-ai/blob/master/backend/agents/copilot_agent.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_app,node_overview_page,node_briefing_page,node_feedback_page,node_sources_page,node_copilot_ui,node_api_client,node_user toneBlue
class node_api_app,node_overview_route,node_briefing_route,node_feedback_route,node_upload_route,node_copilot_route toneAmber
class node_schema_mapper,node_store,node_analytics toneMint
class node_overview_agent,node_briefing_agent,node_feedback_agent,node_copilot_agent toneRose
class node_claude toneIndigo
```

## Components

### Dashboard

- [Page router](https://github.com/karan8989-ux/neemans-ai/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Business overview](https://github.com/karan8989-ux/neemans-ai/blob/master/frontend/src/pages/OverviewPage.tsx): `frontend/src/pages/OverviewPage.tsx`
- [Daily briefing](https://github.com/karan8989-ux/neemans-ai/blob/master/frontend/src/pages/BriefingPage.tsx): `frontend/src/pages/BriefingPage.tsx`
- [Feedback explorer](https://github.com/karan8989-ux/neemans-ai/blob/master/frontend/src/pages/FeedbackPage.tsx): `frontend/src/pages/FeedbackPage.tsx`
- [Data sources](https://github.com/karan8989-ux/neemans-ai/blob/master/frontend/src/pages/DataSourcesPage.tsx): `frontend/src/pages/DataSourcesPage.tsx`
- [Copilot chat](https://github.com/karan8989-ux/neemans-ai/blob/master/frontend/src/components/copilot/AIBusinessCopilot.tsx): `frontend/src/components/copilot/AIBusinessCopilot.tsx`
- [API client](https://github.com/karan8989-ux/neemans-ai/blob/master/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### API routes

- [FastAPI app](https://github.com/karan8989-ux/neemans-ai/blob/master/backend/main.py): `backend/main.py`
- [Overview routes](https://github.com/karan8989-ux/neemans-ai/blob/master/backend/routers/overview.py): `backend/routers/overview.py`
- [Briefing routes](https://github.com/karan8989-ux/neemans-ai/blob/master/backend/routers/briefing.py): `backend/routers/briefing.py`
- [Feedback routes](https://github.com/karan8989-ux/neemans-ai/blob/master/backend/routers/feedback.py): `backend/routers/feedback.py`
- [Upload routes](https://github.com/karan8989-ux/neemans-ai/blob/master/backend/routers/upload.py): `backend/routers/upload.py`
- [Copilot routes](https://github.com/karan8989-ux/neemans-ai/blob/master/backend/routers/copilot.py): `backend/routers/copilot.py`

### Data and analytics

- [CSV mapping](https://github.com/karan8989-ux/neemans-ai/blob/master/backend/services/schema_mapper.py): `backend/services/schema_mapper.py`
- [Dataset store](https://github.com/karan8989-ux/neemans-ai/blob/master/backend/services/data_store.py): `backend/services/data_store.py`
- [Pandas analytics](https://github.com/karan8989-ux/neemans-ai/blob/master/backend/services/analytics.py): `backend/services/analytics.py`

### AI insights

- [Overview insights](https://github.com/karan8989-ux/neemans-ai/blob/master/backend/agents/overview_agent.py): `backend/agents/overview_agent.py`
- [Briefing generator](https://github.com/karan8989-ux/neemans-ai/blob/master/backend/agents/briefing_agent.py): `backend/agents/briefing_agent.py`
- [Feedback recommendations](https://github.com/karan8989-ux/neemans-ai/blob/master/backend/agents/feedback_agent.py): `backend/agents/feedback_agent.py`
- [Copilot agent](https://github.com/karan8989-ux/neemans-ai/blob/master/backend/agents/copilot_agent.py): `backend/agents/copilot_agent.py`

### Other components

- **Business user**
- **Anthropic Claude**

## Connections

- Business user → Page router: uses (evidence: `README.md`)
- Page router → Business overview: routes to (evidence: `frontend/src/App.tsx`)
- Page router → Daily briefing: routes to (evidence: `frontend/src/App.tsx`)
- Page router → Feedback explorer: routes to (evidence: `frontend/src/App.tsx`)
- Page router → Data sources: routes to (evidence: `frontend/src/App.tsx`)
- Page router → Copilot chat: renders (evidence: `frontend/src/App.tsx`)
- Business overview → API client: requests data
- Daily briefing → API client: requests data
- Feedback explorer → API client: requests data
- Data sources → API client: uploads CSVs
- Copilot chat → API client: asks questions
- API client → FastAPI app: calls API (evidence: `README.md`)
- FastAPI app → Overview routes: registers (evidence: `backend/main.py`)
- FastAPI app → Briefing routes: registers (evidence: `backend/main.py`)
- FastAPI app → Feedback routes: registers (evidence: `backend/main.py`)
- FastAPI app → Upload routes: registers (evidence: `backend/main.py`)
- FastAPI app → Copilot routes: registers (evidence: `backend/main.py`)
- FastAPI app → Dataset store: loads demo data (evidence: `backend/main.py`)
- Upload routes → CSV mapping: validates CSV (evidence: `backend/routers/upload.py`)
- Upload routes → Dataset store: replaces dataset (evidence: `backend/routers/upload.py`)
- CSV mapping → Anthropic Claude: maps ambiguous columns
- Overview routes → Pandas analytics: reads aggregates (evidence: `backend/routers/overview.py`)
- Briefing routes → Pandas analytics: reads aggregates (evidence: `backend/routers/briefing.py`)
- Feedback routes → Pandas analytics: reads feedback (evidence: `backend/routers/feedback.py`)
- Copilot routes → Copilot agent: dispatches chat (evidence: `backend/routers/copilot.py`)
- Pandas analytics → Dataset store: reads datasets (evidence: `backend/services/analytics.py`)
- Overview routes → Overview insights: requests highlights (evidence: `README.md`)
- Briefing routes → Briefing generator: generates briefing (evidence: `backend/routers/briefing.py`)
- Feedback routes → Feedback recommendations: requests recommendations (evidence: `backend/routers/feedback.py`)
- Overview insights → Pandas analytics: uses aggregates (evidence: `backend/agents/overview_agent.py`)
- Briefing generator → Pandas analytics: uses aggregates (evidence: `backend/agents/briefing_agent.py`)
- Feedback recommendations → Pandas analytics: uses aggregates (evidence: `backend/agents/feedback_agent.py`)
- Copilot agent → Pandas analytics: gathers context (evidence: `backend/agents/copilot_agent.py`)
- Overview insights → Anthropic Claude: generates insights
- Briefing generator → Anthropic Claude: generates briefing
- Feedback recommendations → Anthropic Claude: generates recommendations (evidence: `backend/agents/feedback_agent.py`)
- Copilot agent → Anthropic Claude: generates answer (evidence: `backend/agents/copilot_agent.py`)
