Content
# Groww Pulse Agent
A pair of services implementing an autonomous customer feedback analysis agent. It automatically scrapes app store reviews (Google Play Store & Apple App Store) for the Groww mobile application, scrubs PII, normalizes the data, analyzes feedback trends using Groq LLM, appends the generated report directly to a Google Doc, and sends email notifications to stakeholders using a custom Server-Sent Events (SSE) Model Context Protocol (MCP) Server.
---
## 🏗️ Architecture
```
+------------------------------------------+
| Frontend Dashboard | (Hosted on Vercel)
| (Vercel Domain) |
+------------------------------------------+
| /api/* rewrites
v
+------------------------------------------+
| Python Backend API | (Hosted on Railway)
| (Railway Domain) |
+------------------------------------------+
| MCP SSE Session
v
+------------------------------------------+
| Google Workspace MCP Server | (Hosted on Railway)
| (MCP Server Domain) |
+------------------------------------------+
| |
v v
Google Docs API Gmail API
```
---
## 📁 Repository Structure
```
├── api/ # Vercel Serverless Function entrypoints
├── data/ # Raw/Normalized review caches and backups
├── docs/ # Product requirements and specifications
├── output/ # Locally generated report backups (Markdown and TXT format)
├── src/ # Core source code
│ ├── app.py # FastAPI Application and Background Task runner
│ ├── downloader.py # Live Review Scrapers (App Store & Play Store)
│ ├── importer.py # Data Importers and Date Filters
│ ├── scrubber.py # PII Masking and String Cleaners
│ ├── analyzer.py # Groq LLM Prompting & Report Generation Engine
│ └── publisher.py # MCP client wrapper connecting to Google APIs
├── tests/ # Automated pytest suite (Unit and Playwright browser tests)
├── requirements.txt # Python dependencies
└── vercel.json # Frontend routing and API rewrite rules
```
---
## ⚙️ Configuration & Environment Variables
### 1. Python Backend (`Groww-Pulse-Agent`)
Create a `.env` file in the root folder for local development:
```env
GROQ_API_KEY=your_groq_api_key
GOOGLE_DOC_ID=your_google_doc_id
RECIPIENT_EMAIL=your_recipient_email@example.com
MCP_SERVER_URL=your_local_mcp_server_sse_url
```
### 2. Google Workspace MCP Server (`MCP-Server---Groww-Pulse`)
The MCP Server parses these variables from its own environment:
```env
GOOGLE_CLIENT_ID=your_google_oauth_client_id
GOOGLE_CLIENT_SECRET=your_google_oauth_client_secret
GOOGLE_REDIRECT_URI=your_oauth_redirect_uri
GOOGLE_REFRESH_TOKEN=your_authenticated_google_refresh_token
GOOGLE_ACCESS_TOKEN=your_authenticated_google_access_token
PORT=3000
MCP_TRANSPORT=sse
LOG_LEVEL=info
```
---
## 🚀 Local Setup & Running
### Step 1: Install Dependencies
Install dependencies on your local machine:
```bash
# In Backend directory:
pip install -r requirements.txt
# In MCP Server directory:
npm install
```
### Step 2: Authenticate Google OAuth
Run the login script in the MCP server folder to generate your local credential tokens:
```bash
npm run auth:login
```
*(This deletes stale files, boots a local callback on port 3000, and starts the Google auth flow to grant scopes. It saves the resulting tokens in `.gstore/tokens.json`)*.
### Step 3: Run the local servers
Expose the MCP server locally in SSE mode:
```bash
# In the MCP Server directory:
set MCP_TRANSPORT=sse&& npm run start
```
Start the FastAPI Python app locally:
```bash
# In the Groww-Pulse-Agent directory:
py -m uvicorn src.app:app --host 127.0.0.1 --port 8000
```
Open the local URL in your browser to view the local dashboard and trigger review pulse runs.
---
## ☁️ Cloud Deployment
1. **Frontend**: Deploy to Vercel. Vercel matches rewrite rules to proxy all API requests to Railway.
2. **Backend**: Deploy to Railway.
3. **MCP Server**: Deploy to Railway as a persistent Docker container, exposing it via port `3000` with the `MCP_TRANSPORT=sse` environment variable.
4. **Integration**: Set `MCP_SERVER_URL` in the Railway Python backend dashboard to point to the MCP server's public domain.
