Zomato Reviews Analysis System

A complete web application for analyzing Zomato restaurant reviews using AI-powered analysis with both backend API and frontend interface.

Project Structure

Zomato-Reviews-Analysis/
├── backend/                    # Backend API code
│   ├── analysis_agent/        # AI analysis engine
│   ├── controller/            # Application controllers
│   ├── routes/                # API routes
│   ├── main.py               # Backend entry point
│   ├── scrapper.py           # Data scraping utilities
│   ├── setup.py              # Setup and configuration
│   ├── requirements.txt      # Python dependencies
│   └── zomato_reviews.sqlite  # Primary database file
├── frontend/                  # Frontend web interface
│   ├── index.html            # Main HTML page
│   ├── styles.css            # CSS styling
│   └── script.js             # JavaScript functionality
├── main.py                   # Main application entry point
├── start.py                  # Startup script with environment checks
├── zomato_reviews.sqlite     # Database file (backup/alternative)
├── README.md                 # This file
└── .env                      # Environment variables (create this)

System Architecture

The following High-Level Design (HLD) diagram shows the complete system architecture including data flow, AI analysis engine, and frontend coordination:

graph TB
    subgraph "Data Sources"
        GOOGLE_PLAY["Google Play Store\nZomato Reviews"]
    end

    subgraph "Data Collection"
        SCRAPER["Review Scraper\nParallel Collection\n16 Workers"]
    end

    subgraph "Data Storage"
        DATABASE[("SQLite Database\nStores All Reviews")]
    end

    subgraph "AI Analysis Engine"
        AGENT["AnalyzerEngine\nMain Orchestrator Agent\nTool Calling & Decision Making"]
        
        subgraph "Specialized Tools"
            DATA_TOOL["Data Retrieval Tool\nToken-Aware Batching"]
            TOPIC_TOOL["Topic Extraction Tool\nLLM-Based Extraction"]
            CONSOL_TOOL["Topic Consolidation Tool\nTwo-Step Consolidation"]
            ANALYSIS_TOOL["Iterative Analysis Tool\nTrend Detection"]
            REPORT_TOOL["Report Generation Tool\nCSV Export"]
        end
        
        subgraph "Processing Pipeline"
            RETRIEVE["Data Retrieval\nT-30 to T with Limits"]
            EXTRACT["Parallel Topic Extraction\n5 Days Simultaneously"]
            CONSOLIDATE["Two-Step Consolidation\nPer-Day → Cross-Day"]
            ANALYZE["Trend Analysis\nTopic Persistence"]
            REPORT["Report Generation\nCSV Matrix"]
        end
    end

    subgraph "External AI"
        OPENAI["OpenAI GPT-4o-mini\nLLM Processing\nStructured Outputs & Pydantic Models\nRetry Logic & Error Handling"]
    end

    subgraph "Frontend Interface"
        WEB_UI["Web Interface\nHTML/CSS/JavaScript\nForm Validation & Results Display"]
        API_GATEWAY["FastAPI Gateway\nRESTful Endpoints\nCORS & Error Handling"]
    end

    subgraph "Output"
        CSV["CSV Report\nTopic Trends Matrix\nConsolidation Metrics"]
        WEB_RESULTS["Web Results\nInteractive Analysis\nReal-time Feedback"]
    end

    linkStyle default stroke:#000000,stroke-width:2px,fill:none

    GOOGLE_PLAY --> SCRAPER
    SCRAPER --> DATABASE
    DATABASE --> AGENT

    AGENT --> DATA_TOOL
    AGENT --> TOPIC_TOOL
    AGENT --> CONSOL_TOOL
    AGENT --> ANALYSIS_TOOL
    AGENT --> REPORT_TOOL

    DATA_TOOL --> RETRIEVE
    TOPIC_TOOL --> EXTRACT
    CONSOL_TOOL --> CONSOLIDATE
    ANALYSIS_TOOL --> ANALYZE
    REPORT_TOOL --> REPORT

    TOPIC_TOOL --> OPENAI
    CONSOL_TOOL --> OPENAI

    WEB_UI --> API_GATEWAY
    API_GATEWAY --> AGENT
    AGENT --> API_GATEWAY
    API_GATEWAY --> WEB_RESULTS

    REPORT --> CSV

    EXTRACT -.->|Parallel| EXTRACT
    CONSOLIDATE -.->|Parallel| CONSOLIDATE

    classDef default fill:#fdfdfd,stroke:#111,stroke-width:1.5px,color:#111
    classDef shaded fill:#efefef,stroke:#111,stroke-width:1.5px,color:#000
    classDef darker fill:#dcdcdc,stroke:#000,stroke-width:1.5px,color:#000
    classDef cluster fill:#f5f5f5,stroke:#000,stroke-width:2px,color:#000,font-weight:bold

    class GOOGLE_PLAY,SCRAPER,DATABASE,AGENT,OPENAI,WEB_UI,API_GATEWAY,CSV,WEB_RESULTS shaded
    class DATA_TOOL,TOPIC_TOOL,CONSOL_TOOL,ANALYSIS_TOOL,REPORT_TOOL darker
    class RETRIEVE,EXTRACT,CONSOLIDATE,ANALYZE,REPORT shaded

Loading

Architecture Components

Data Flow:

1. Data Collection: Parallel scraping from Google Play Store with 16 workers
2. Storage: SQLite database for persistent review storage
3. AI Processing: Agent-driven analysis with specialized tools
4. Frontend Integration: RESTful API gateway connecting web interface to analysis engine
5. Output: Both CSV reports and interactive web results

Key Features:

• Parallel Processing: Simultaneous topic extraction and consolidation
• Token-Aware Batching: Efficient data processing with token limits
• Two-Step Consolidation: Per-day then cross-day topic consolidation
• Real-time Feedback: Web interface with loading states and error handling
• Structured Outputs: Pydantic models ensuring data consistency

Features

Backend API

• AI-Powered Analysis: Uses OpenAI GPT models for intelligent review analysis
• Agent-Driven Processing: Automated tool orchestration for data processing
• Topic Generation: Extracts and consolidates topics from reviews
• Confidence Scoring: Provides analysis confidence metrics
• RESTful API: Clean API endpoints for frontend integration

Frontend Interface

• UI: Clean, responsive design with gradient backgrounds
• Form Validation: Client-side validation for inputs
• Real-time Feedback: Loading states and error handling
• Results Display: Comprehensive analysis results visualization
• Mobile Responsive: Works on desktop and mobile devices

Setup Instructions

Prerequisites

• Python 3.8 or higher
• OpenAI API key
• Internet connection

Installation

1. Clone the repository

   git clone <repository-url>
   cd Zomato-Reviews-Analysis

2. Create virtual environment

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

   pip3 install -r backend/requirements.txt

4. Set up environment variables Create a .env file in the root directory:

   OPENAI_API_KEY=your_openai_api_key_here
   

5. Verify setup

   python3 backend/setup.py

Usage

Running the Application

1. Start the complete system

   python3 start.py

2. Access the application

   • Frontend: http://localhost:8000/
   • API Documentation: http://localhost:8000/api/docs
   • Health Check: http://localhost:8000/api/health

Using the Frontend

1. Open the web interface at http://localhost:8000/
2. Enter Zomato App Link: Paste the URL of the Zomato restaurant page
3. Select Target Date: Choose the target date for analysis (T-30 to T)
4. Click "Analyze Reviews": The system will process the data and display results

API Endpoints

• POST /api/v1/review - Main analysis endpoint
• GET /api/v1/health - Health check
• GET /api/v1/agent-status - Agent status and tool availability

Analysis Process

The system performs the following analysis steps:

1. Data Retrieval: Fetches reviews from T-30 to target date T
2. Topic Generation: Uses AI to extract topics from daily reviews
3. Topic Consolidation: Intelligently consolidates similar topics
4. Iterative Analysis: Performs iterative analysis when sufficient data is available
5. Report Generation: Creates comprehensive analysis reports

Configuration

Environment Variables

• OPENAI_API_KEY: Your OpenAI API key (required)

Database

• The system uses SQLite database (zomato_reviews.sqlite)
• Primary database: backend/zomato_reviews.sqlite (used by main application)
• Alternative database: zomato_reviews.sqlite (root directory, used by backend-only mode)
• The main application expects the database in the backend/ directory

Frontend Features

• Responsive Design: Works on all screen sizes
• Form Validation: Real-time input validation
• Loading States: Visual feedback during analysis
• Error Handling: User-friendly error messages
• Results Visualization: Clean display of analysis results
• Keyboard Shortcuts: Ctrl+Enter to submit form

Troubleshooting

Common Issues

1. "OPENAI_API_KEY not found"

   • Ensure .env file exists with valid API key

2. "Database not found"

   • Check that zomato_reviews.sqlite is in backend/ directory

3. Frontend not loading

   • Ensure frontend/ directory contains HTML, CSS, and JS files

4. API connection errors

   • Check that backend is running on port 8000
   • Verify CORS settings if accessing from different domain

Development Mode

For development with auto-reload:

python3 -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

📝 API Documentation

Full API documentation is available at:

• Swagger UI: http://localhost:8000/api/docs
• ReDoc: http://localhost:8000/api/redoc