---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-18
name: User_Manual
status: active
tags:
- domain/analytics
- status/active
- tech/azure-ad
- tech/claude
- tech/docker
- tech/node
- type/sop
type: sop
---

# Social Listening Pipeline: User Manual

## What This Tool Does

The **Social Listening Pipeline** is an automated research tool that scrapes public data from TikTok, Instagram, and YouTube, analyzes the content using Claude AI, and generates professional, client-ready HTML reports. It helps marketing teams and researchers identify trends, opportunities, and competitive intelligence quickly.

## Who Uses It

- **Marketing Managers**: To track brand sentiment and competitor activity.
- **Social Media Strategists**: To discover trending topics and hashtags.
- **Client Consultants**: To produce white-label reports for stakeholders.

## How to Access

### Local Development
1. Ensure you have **Docker** and **Node.js 20+** installed.
2. Clone the repository.
3. Create a `.env` file based on `.env.example` (see Developer Manual for details).
4. Start the services:
   ```bash
   docker compose up -d
   ```
5. Access the dashboard at `http://localhost:3456` (or the port defined in your `.env` as `DASHBOARD_PORT`).

### Production
Deploy using the provided `docker-compose.prod.yml` file alongside the base `docker-compose.yml`.

## Main Workflows

### 1. Creating a New Report

1. **Log in** to the dashboard.
   - If Azure AD SSO is enabled, you will be redirected to your organization's login.
   - Otherwise, use the local credentials (`DASH_USER` and `DASH_PASS` in `.env`).
2. **Navigate to the "New Report" tab.**
3. **Fill in the Client Brief:**
   - **Client Name**: Name of the client.
   - **Category**: Industry or topic (e.g., "Fitness", "Tech").
   - **Platforms**: Select TikTok, Instagram, YouTube.
   - **Hashtags**: Enter target hashtags.
   - **Apify Budget**: Set a maximum spend limit for scraping costs (optional).
4. **Click "Run Pipeline"**.
5. **Monitor Progress:**
   - The dashboard updates in real-time via Server-Sent Events (SSE).
   - Watch the progress bar and live cost tracking.
   - The pipeline runs 8 stages: Brief Validation, Strategy Review, Discovery Scrape, Data Review, Enrichment Scrape, Pre-Report Review, Desk Research, and Report Generation.
6. **Download the Report:**
   - Once complete, the final HTML report is available for download.
   - It includes video embeds (YouTube/Instagram) and trend analysis.

### 2. Saving and Loading Briefs

1. Go to the "Saved Briefs" tab.
2. Click "Save Brief" to store your current configuration server-side.
3. Select a saved brief from the list and click "Load" to populate the form.

### 3. Viewing Run History

1. Go to the "Run History" tab.
2. View past runs with details including:
   - Date and time
   - Cost breakdown (Claude AI and Apify)
   - Status (Success/Error)
3. **Download** previous reports or **Delete** old entries.

## FAQ

**Q: What are the required API keys?**
A: You need an **Apify API Token** for scraping and an **Anthropic API Key** for AI analysis. Both must be set in your `.env` file.

**Q: How much does a run cost?**
A: Costs depend on the length of the analysis and scraping scope. You can set an `APIFY_COST_LIMIT` in `.env` to cap scraping expenses. AI costs are tracked in real-time but not hard-capped by default.

**Q: Can I use this with my company's Azure AD?**
A: Yes. Set `__SSO_ENABLED = true` in `frontend/config.js` and provide your `AZURE_TENANT_ID` and `AZURE_CLIENT_ID` in the environment variables.

**Q: What happens if the Apify scrape fails?**
A: The pipeline will log an error and stop. Check the dashboard logs for details. Ensure your Apify API token is valid and has sufficient credits.

**Q: How do I reset my local password?**
A: Update `DASH_PASS` in your `.env` file and restart the `social-listening` container:
   ```bash
   docker compose restart social-listening
   ```

## Related
- [[05 Aimpress LTD/Projects/Social Listening Pipeline]]
- [[03 Resources/Developer Manual]]