# gowthamr1225/google_reviews-analyzing architecture

> Architecture diagram of the GitHub repository gowthamr1225/google_reviews-analyzing, 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/gowthamr1225/google_reviews-analyzing
- Repository: https://github.com/gowthamr1225/google_reviews-analyzing

## Overview

#### Purpose
This repository is a business-review analytics prototype that turns Google Maps-style customer reviews into sentiment, themes, trends, reputation signals, and operational recommendations. It is oriented around an interactive dashboard and an exploratory notebook workflow.

#### Entry Points
- `app.py` is the likely application/dashboard entry point for serving the analyzer experience.
- `BUSINESS REPUTATION & INSIGHTS ANALYZER.ipynb` is the primary exploratory or development workflow for data preparation, analysis, and model experimentation.
- `README.md` defines the intended six-stage review-analysis product behavior.

#### Review Data Layer
The system works from locally stored review datasets rather than a live ingestion service in this repository:
- `reviews.xlsx`
- `reviews.pkl`
- `reviews_clean.parquet`

The parallel cleaned exports (`reviews_clean.parquet`, `reviews_clean.xlsx`) form the likely boundary between raw/extracted reviews and downstream NLP/dashboard consumption.

#### NLP and Insight Pipeline
The intended analysis flow is: review text → preprocessing → sentiment classification → thematic categorization → trend/reputation aggregation → LLM-generated recommendations. The notebook is the most likely location for implementing or validating these stages:
- `BUSINESS REPUTATION & INSIGHTS ANALYZER.ipynb`
- `reviews_clean.parquet`

Outputs are business-facing insights rather than only per-review labels: recurring complaints, strengths, service/pricing/staff themes, temporal trends, and reputation scoring.

#### LLM Recommendation Boundary
Recommendation generation is designed to be separated from deterministic review processing. The README identifies Langflow, Groq API, Hugging Face models, prompt engineering, and transformer-based NLP as the AI stack. This creates an external-service boundary: cleaned/aggregated review evidence is passed into model workflows, which return summaries and tailored business actions.
- `README.md`
- `app.py`

#### Dashboard and Presentation
The presentation layer is intended to provide interactive decision support, with Streamlit or Gradio named as the frontend runtime. It should consume analyzed review data and generated insights to expose sentiment, themes, trends, reputation scores, and recommendations.
- `app.py`
- `reviews_clean.xlsx`

#### External Data and Infrastructure
SerpAPI is the stated upstream source for Google Maps review extraction, but no dedicated ingestion module is present in the repository tree. The current checked-in datasets therefore act as the operational data source. Groq and Hugging Face represent external model dependencies; Langflow is the stated workflow/orchestration environment.

Main entry points: [`BUSINESS REPUTATION & INSIGHTS ANALYZER.ipynb`](https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/BUSINESS%20REPUTATION%20%26%20INSIGHTS%20ANALYZER.ipynb) (Review preprocessing), [`app.py`](https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/app.py) (Interactive dashboard), [`reviews_clean.parquet`](https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/reviews_clean.parquet) (Clean review data), [`README.md`](https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/README.md) (Six-stage product behavior)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Review Data"]
  node_serpapi{{"SerpAPI / Google Maps<br/>external review source"}}
  node_raw_xlsx["Raw reviews workbook<br/>review dataset<br/>[reviews.xlsx]"]
  node_raw_pkl["Raw reviews pickle<br/>review dataset<br/>[reviews.pkl]"]
  node_clean_parquet[("Clean review data<br/>cleaned dataset")]
  node_clean_xlsx["Clean review workbook<br/>cleaned dataset<br/>[reviews_clean.xlsx]"]
end

subgraph group_analysis["Analysis Pipeline"]
  node_notebook["Analysis notebook<br/>exploratory workflow"]
  node_preprocessing["Review preprocessing<br/>NLP stage"]
  node_sentiment["Sentiment classification<br/>NLP stage"]
  node_themes["Theme categorization<br/>NLP stage"]
  node_reputation["Trends &amp; reputation<br/>insight aggregation"]
end

subgraph group_ai["AI Recommendations"]
  node_llm_workflow{{"Langflow model workflow<br/>LLM orchestration<br/>[README.md]"}}
  node_model_apis{{"Groq &amp; Hugging Face<br/>external model services"}}
  node_recommendations["Business recommendations<br/>generated insight<br/>[app.py]"]
end

subgraph group_presentation["Decision Support"]
  node_dashboard["Interactive dashboard<br/>application entry point<br/>[app.py]"]
end

node_product_spec["Six-stage product behavior<br/>product specification<br/>[README.md]"]

node_serpapi -.->|"intended extraction"| node_raw_xlsx
node_raw_xlsx -->|"review text"| node_preprocessing
node_raw_pkl -->|"alternate source"| node_preprocessing
node_preprocessing -->|"cleaned export"| node_clean_parquet
node_preprocessing -->|"normalized reviews"| node_sentiment
node_clean_parquet -->|"downstream input"| node_sentiment
node_sentiment -->|"labeled reviews"| node_themes
node_themes -->|"theme evidence"| node_reputation
node_reputation -->|"aggregated evidence"| node_llm_workflow
node_llm_workflow -->|"model calls"| node_model_apis
node_model_apis -->|"generated actions"| node_recommendations
node_reputation -->|"scores and trends"| node_dashboard
node_recommendations -->|"business actions"| node_dashboard
node_clean_xlsx -->|"cleaned review data"| node_dashboard
node_clean_parquet -.->|"parallel export"| node_clean_xlsx
node_product_spec -.->|"defines intended flow"| node_notebook
node_notebook -.->|"implements and validates"| node_preprocessing
node_product_spec -.->|"defines experience"| node_dashboard

click node_raw_xlsx "https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/reviews.xlsx"
click node_raw_pkl "https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/reviews.pkl"
click node_clean_parquet "https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/reviews_clean.parquet"
click node_clean_xlsx "https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/reviews_clean.xlsx"
click node_notebook "https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/BUSINESS%20REPUTATION%20%26%20INSIGHTS%20ANALYZER.ipynb"
click node_preprocessing "https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/BUSINESS%20REPUTATION%20%26%20INSIGHTS%20ANALYZER.ipynb"
click node_sentiment "https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/BUSINESS%20REPUTATION%20%26%20INSIGHTS%20ANALYZER.ipynb"
click node_themes "https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/BUSINESS%20REPUTATION%20%26%20INSIGHTS%20ANALYZER.ipynb"
click node_reputation "https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/BUSINESS%20REPUTATION%20%26%20INSIGHTS%20ANALYZER.ipynb"
click node_llm_workflow "https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/README.md"
click node_recommendations "https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/app.py"
click node_dashboard "https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/app.py"
click node_product_spec "https://github.com/gowthamr1225/google_reviews-analyzing/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_serpapi,node_raw_xlsx,node_raw_pkl,node_clean_parquet,node_clean_xlsx toneBlue
class node_notebook,node_preprocessing,node_sentiment,node_themes,node_reputation toneAmber
class node_llm_workflow,node_model_apis,node_recommendations toneMint
class node_dashboard toneRose
class node_product_spec toneNeutral
```

## Components

### Review Data

Local datasets are the operational input boundary.

- **SerpAPI / Google Maps**: external review source · Stated upstream extraction source; no ingestion module is present.
- [Raw reviews workbook](https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/reviews.xlsx): review dataset · `reviews.xlsx`
- [Raw reviews pickle](https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/reviews.pkl): review dataset · `reviews.pkl`
- [Clean review data](https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/reviews_clean.parquet): cleaned dataset · Primary machine-readable boundary for downstream NLP. · `reviews_clean.parquet`
- [Clean review workbook](https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/reviews_clean.xlsx): cleaned dataset · Dashboard-friendly cleaned export. · `reviews_clean.xlsx`

### Analysis Pipeline

Notebook-driven deterministic review analysis.

- [Analysis notebook](https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/BUSINESS%20REPUTATION%20%26%20INSIGHTS%20ANALYZER.ipynb): exploratory workflow · Primary development and model-experiment workflow. · `BUSINESS REPUTATION & INSIGHTS ANALYZER.ipynb`
- [Review preprocessing](https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/BUSINESS%20REPUTATION%20%26%20INSIGHTS%20ANALYZER.ipynb): NLP stage · `BUSINESS REPUTATION & INSIGHTS ANALYZER.ipynb`
- [Sentiment classification](https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/BUSINESS%20REPUTATION%20%26%20INSIGHTS%20ANALYZER.ipynb): NLP stage · `BUSINESS REPUTATION & INSIGHTS ANALYZER.ipynb`
- [Theme categorization](https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/BUSINESS%20REPUTATION%20%26%20INSIGHTS%20ANALYZER.ipynb): NLP stage · Identifies service, pricing, staff, strengths, and complaints. · `BUSINESS REPUTATION & INSIGHTS ANALYZER.ipynb`
- [Trends & reputation](https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/BUSINESS%20REPUTATION%20%26%20INSIGHTS%20ANALYZER.ipynb): insight aggregation · Builds temporal trends, recurring signals, and reputation scores. · `BUSINESS REPUTATION & INSIGHTS ANALYZER.ipynb`

### AI Recommendations

External model workflow produces business actions.

- [Langflow model workflow](https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/README.md): LLM orchestration · Separates recommendation generation from deterministic analysis. · `README.md`
- **Groq & Hugging Face**: external model services
- [Business recommendations](https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/app.py): generated insight · Tailored summaries and operational actions. · `app.py`

### Decision Support

Interactive dashboard exposes findings.

- [Interactive dashboard](https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/app.py): application entry point · Presents sentiment, themes, trends, scores, and recommendations. · `app.py`

### Other components

- [Six-stage product behavior](https://github.com/gowthamr1225/google_reviews-analyzing/blob/main/README.md): product specification · `README.md`

## Connections

- SerpAPI / Google Maps → Raw reviews workbook: intended extraction
- Raw reviews workbook → Review preprocessing: review text
- Raw reviews pickle → Review preprocessing: alternate source
- Review preprocessing → Clean review data: cleaned export
- Review preprocessing → Sentiment classification: normalized reviews
- Clean review data → Sentiment classification: downstream input
- Sentiment classification → Theme categorization: labeled reviews
- Theme categorization → Trends & reputation: theme evidence
- Trends & reputation → Langflow model workflow: aggregated evidence
- Langflow model workflow → Groq & Hugging Face: model calls
- Groq & Hugging Face → Business recommendations: generated actions
- Trends & reputation → Interactive dashboard: scores and trends
- Business recommendations → Interactive dashboard: business actions
- Clean review workbook → Interactive dashboard: cleaned review data
- Clean review data → Clean review workbook: parallel export
- Six-stage product behavior → Analysis notebook: defines intended flow
- Analysis notebook → Review preprocessing: implements and validates
- Six-stage product behavior → Interactive dashboard: defines experience