# thevirtualhero/business-analyzer architecture

> Architecture diagram of the GitHub repository thevirtualhero/business-analyzer, 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/thevirtualhero/business-analyzer
- Repository: https://github.com/thevirtualhero/business-analyzer

## Overview

#### Purpose
Business-Analyzer is an LLM-assisted review-intelligence project for local businesses. It turns Google Maps-style customer reviews into sentiment, themes, and business recommendations. The repository is a compact prototype rather than a clearly separated production application.

#### Entry Points
- `google maps review analyser.ipynb` is the likely exploratory/interactive analysis entry point for loading and analyzing reviews.
- `llm and code.py` is the likely scripted LLM integration or automation entry point.
- `README.md` describes intended Streamlit/Gradio deployment, but no frontend source file is present in the tree.

#### Review Data Boundary
- `ReviewsDetails.csv` is the repository’s local review-data input.
- The intended upstream acquisition boundary is SerpAPI/Google Maps Reviews, as described in `README.md`; no API client or credentials file is visible.
- The CSV/notebook boundary separates raw or simulated review records from NLP and LLM analysis.

#### NLP and Classification Stage
The analysis layer is intended to clean review text and derive structured signals:
- Sentiment classification distinguishes positive, negative, and complaint-oriented feedback.
- Thematic categorization identifies recurring operational topics such as service speed, pricing, and staff behavior.
- This stage is represented by the workflow-oriented artifacts `google maps review analyser.ipynb` and `llm and code.py`, with the dataset in `ReviewsDetails.csv`.

#### LLM Insight Generation Stage
The core reasoning flow uses prompt-driven LLM processing to convert review-level signals into summaries and recommendations. The stated model ecosystem is Hugging Face and Langflow (`README.md`), likely invoked or prototyped through `llm and code.py`. Outputs are intended to include operational suggestions, trend-based recommendations, and competitor-related highlights.

#### Presentation and Delivery Boundary
The README positions Streamlit or Gradio as the user-facing deployment runtime, but the repository contains no corresponding app module. Therefore, the current visible delivery mechanism is the notebook (`google maps review analyser.ipynb`), while a dashboard layer remains an intended integration boundary rather than a confirmed implemented component.

#### Runtime and External Dependencies
Material runtimes/services named by the project are Python, notebook execution, Hugging Face models, Langflow, and SerpAPI. `README.md` is the only visible dependency/design declaration; there are no package manifests, deployment descriptors, Langflow exports, or frontend source files in the provided tree. Engineers should treat model selection, API ingestion, and dashboard serving as integration points needing verification inside `llm and code.py` and the notebook.

Main entry points: [`README.md`](https://github.com/thevirtualhero/business-analyzer/blob/main/README.md) (Project design declaration), [`ReviewsDetails.csv`](https://github.com/thevirtualhero/business-analyzer/blob/main/ReviewsDetails.csv) (Local review dataset), [`google maps review analyser.ipynb`](https://github.com/thevirtualhero/business-analyzer/blob/main/google%20maps%20review%20analyser.ipynb) (Interactive analysis), [`llm and code.py`](https://github.com/thevirtualhero/business-analyzer/blob/main/llm%20and%20code.py) (LLM automation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Review Inputs"]
  node_reviews_csv[("Local review dataset<br/>CSV input<br/>[ReviewsDetails.csv]")]
end

subgraph group_analysis["Analysis Workflow"]
  node_notebook["Interactive analysis<br/>Jupyter notebook"]
  node_llm_script["LLM automation<br/>Python script<br/>[llm and code.py]"]
  node_text_cleaning["Review text cleaning<br/>NLP stage"]
  node_classification["Sentiment &amp; theme classification<br/>NLP stage"]
  node_llm_insights["LLM insight generation<br/>reasoning stage"]
  node_recommendations["Business recommendations<br/>analysis output"]
end

subgraph group_integrations["External &amp; Intended Delivery"]
  node_serpapi{{"SerpAPI / Google Maps<br/>upstream reviews API<br/>[README.md]"}}
  node_huggingface{{"Hugging Face models<br/>model provider<br/>[README.md]"}}
  node_langflow{{"Langflow<br/>LLM orchestration<br/>[README.md]"}}
  node_dashboard["Streamlit / Gradio dashboard<br/>intended UI<br/>[README.md]"]
  node_readme["Project design declaration<br/>documentation<br/>[README.md]"]
end

node_serpapi -.->|"intended ingestion"| node_reviews_csv
node_reviews_csv -->|"loads reviews"| node_notebook
node_reviews_csv -->|"processes reviews"| node_llm_script
node_notebook -->|"analyzes"| node_text_cleaning
node_llm_script -->|"automates"| node_text_cleaning
node_text_cleaning -->|"normalized text"| node_classification
node_classification -->|"structured review signals"| node_llm_insights
node_huggingface -.->|"model inference"| node_llm_insights
node_langflow -.->|"prompt workflow"| node_llm_insights
node_llm_insights -->|"generates"| node_recommendations
node_recommendations -->|"interactive results"| node_notebook
node_recommendations -.->|"intended presentation"| node_dashboard
node_readme -.->|"documents"| node_serpapi
node_readme -.->|"documents"| node_huggingface
node_readme -.->|"documents"| node_langflow
node_readme -.->|"proposes"| node_dashboard

click node_serpapi "https://github.com/thevirtualhero/business-analyzer/blob/main/README.md"
click node_reviews_csv "https://github.com/thevirtualhero/business-analyzer/blob/main/ReviewsDetails.csv"
click node_notebook "https://github.com/thevirtualhero/business-analyzer/blob/main/google%20maps%20review%20analyser.ipynb"
click node_llm_script "https://github.com/thevirtualhero/business-analyzer/blob/main/llm%20and%20code.py"
click node_huggingface "https://github.com/thevirtualhero/business-analyzer/blob/main/README.md"
click node_langflow "https://github.com/thevirtualhero/business-analyzer/blob/main/README.md"
click node_dashboard "https://github.com/thevirtualhero/business-analyzer/blob/main/README.md"
click node_readme "https://github.com/thevirtualhero/business-analyzer/blob/main/README.md"

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_reviews_csv toneBlue
class node_notebook,node_llm_script,node_text_cleaning,node_classification,node_llm_insights,node_recommendations toneAmber
class node_serpapi,node_huggingface,node_langflow,node_dashboard,node_readme toneMint
```

## Components

### Review Inputs

- [Local review dataset](https://github.com/thevirtualhero/business-analyzer/blob/main/ReviewsDetails.csv): CSV input · `ReviewsDetails.csv`

### Analysis Workflow

- [Interactive analysis](https://github.com/thevirtualhero/business-analyzer/blob/main/google%20maps%20review%20analyser.ipynb): Jupyter notebook · Current visible analysis and delivery surface. · `google maps review analyser.ipynb`
- [LLM automation](https://github.com/thevirtualhero/business-analyzer/blob/main/llm%20and%20code.py): Python script · Likely scripted integration entry point. · `llm and code.py`
- **Review text cleaning**: NLP stage
- **Sentiment & theme classification**: NLP stage · Derives sentiment, complaints, and operational themes.
- **LLM insight generation**: reasoning stage · Produces summaries, recommendations, and competitor highlights.
- **Business recommendations**: analysis output

### External & Intended Delivery

- [SerpAPI / Google Maps](https://github.com/thevirtualhero/business-analyzer/blob/main/README.md): upstream reviews API · Intended acquisition source; no client is visible. · `README.md`
- [Hugging Face models](https://github.com/thevirtualhero/business-analyzer/blob/main/README.md): model provider · `README.md`
- [Langflow](https://github.com/thevirtualhero/business-analyzer/blob/main/README.md): LLM orchestration · `README.md`
- [Streamlit / Gradio dashboard](https://github.com/thevirtualhero/business-analyzer/blob/main/README.md): intended UI · Documented deployment target without a visible app module. · `README.md`
- [Project design declaration](https://github.com/thevirtualhero/business-analyzer/blob/main/README.md): documentation · Declares integrations and intended deployment. · `README.md`

## Connections

- SerpAPI / Google Maps → Local review dataset: intended ingestion
- Local review dataset → Interactive analysis: loads reviews
- Local review dataset → LLM automation: processes reviews
- Interactive analysis → Review text cleaning: analyzes
- LLM automation → Review text cleaning: automates
- Review text cleaning → Sentiment & theme classification: normalized text
- Sentiment & theme classification → LLM insight generation: structured review signals
- Hugging Face models → LLM insight generation: model inference
- Langflow → LLM insight generation: prompt workflow
- LLM insight generation → Business recommendations: generates
- Business recommendations → Interactive analysis: interactive results
- Business recommendations → Streamlit / Gradio dashboard: intended presentation
- Project design declaration → SerpAPI / Google Maps: documents
- Project design declaration → Hugging Face models: documents
- Project design declaration → Langflow: documents
- Project design declaration → Streamlit / Gradio dashboard: proposes