our-claude-skills/ga-agent-skills/docs/PROJECT-PLAN.md

# GA Agent Project Plan (Revised)

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────┐
│                     Infrastructure                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐   │
│  │ GA4 MCP      │  │ BigQuery MCP │  │ Dimension Explorer│   │
│  │ (install)    │  │ (install)    │  │ (build - small)  │   │
│  └──────────────┘  └──────────────┘  └──────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     Claude Skill                             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │ 15-ourdigital-ga-agent                                │   │
│  │ • Interactive analysis                                │   │
│  │ • Report generation                                   │   │
│  │ • Period comparisons                                  │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                  Standalone Services (Later)                 │
│  ┌────────────────────┐  ┌────────────────────────────┐     │
│  │ ga4-slack-reporter │  │ ga4-realtime-watcher       │     │
│  │ (Python service)   │  │ (defer or API-based)       │     │
│  └────────────────────┘  └────────────────────────────┘     │
└─────────────────────────────────────────────────────────────┘
```

---

## Components

| # | Component | Type | Priority | Effort |
|---|-----------|------|----------|--------|
| 1 | MCP Setup | Infrastructure | P0 | Low |
| 2 | ga-agent-skill | Claude Skill | P0 | Medium |
| 3 | dimension-explorer | MCP Server / CLI | P1 | Low |
| 4 | slack-reporter | Standalone Service | P2 | Medium |
| 5 | realtime-watcher | Standalone Service | P3 | High (defer) |

---

## Component 1: MCP Setup

**Location:** `01-mcp-setup/`

**Goal:** Install and configure existing MCP servers

### Tasks

- [ ] Google Cloud project setup
  - [ ] Enable Analytics Data API
  - [ ] Enable Analytics Admin API
  - [ ] Enable BigQuery API
- [ ] Service account creation
  - [ ] Create service account
  - [ ] Grant Analytics Viewer role
  - [ ] Grant BigQuery Data Viewer role
  - [ ] Download JSON key
- [ ] GA4 property access
  - [ ] Add service account to GA4 property
- [ ] Install GA4 MCP server
  - [ ] Clone `googleanalytics/google-analytics-mcp`
  - [ ] Configure credentials
  - [ ] Test connection
- [ ] Install BigQuery MCP server
  - [ ] Configure `@ergut/mcp-bigquery-server`
  - [ ] Verify GA4 export dataset access
- [ ] Add to Claude Code config
  - [ ] Update `~/.claude/mcp_servers.json`
  - [ ] Verify with `mcp-cli servers`

### Deliverables

- `01-mcp-setup/setup-guide.md` - Step-by-step instructions
- `01-mcp-setup/mcp-config.example.json` - Example MCP configuration
- Working MCP connections verified

---

## Component 2: GA Agent Skill (Core)

**Location:** `02-ga-agent-skill/` → Final: `ourdigital-custom-skills/15-ourdigital-ga-agent/`

**Goal:** Interactive GA4 analysis and reporting skill

### Features

| Feature | Description |
|---------|-------------|
| Traffic Analysis | Users, sessions, pageviews with trends |
| Period Comparison | WoW, MoM, YoY comparisons |
| Top Content | Pages, sources, campaigns |
| Report Generation | HTML/PDF reports |
| BigQuery Queries | Complex analysis on exported data |

### Triggers (EN/KR)

- "Analyze GA4 traffic" / "GA4 트래픽 분석"
- "Compare last week vs this week" / "지난주 대비 비교"
- "Generate traffic report" / "트래픽 리포트 생성"
- "Top landing pages" / "인기 랜딩 페이지"
- "Query BigQuery for GA data" / "BigQuery GA 데이터 조회"

### Structure

```
15-ourdigital-ga-agent/
├── SKILL.md
├── scripts/
│   ├── analyze_traffic.py
│   ├── compare_periods.py
│   ├── top_content.py
│   └── generate_report.py
├── templates/
│   └── report.html
├── references/
│   └── ga4-api-reference.md
└── examples/
    └── sample-queries.md
```

### Tasks

- [ ] Create SKILL.md with triggers
- [ ] Build analysis scripts
  - [ ] analyze_traffic.py
  - [ ] compare_periods.py
  - [ ] top_content.py
- [ ] Create report template
- [ ] Add examples
- [ ] Test with Claude Code
- [ ] Move to `ourdigital-custom-skills/15-ourdigital-ga-agent/`

---

## Component 3: Dimension Explorer

**Location:** `03-dimension-explorer/`

**Goal:** Validate GA4 dimensions/metrics with explanations

### Options

| Option | Pros | Cons |
|--------|------|------|
| **A. MCP Server** | Claude can use directly | More setup |
| **B. CLI Tool** | Simple, standalone | Manual invocation |
| **C. Reference JSON** | No code needed | Static, needs refresh |

**Recommendation:** Start with C (Reference JSON), upgrade to A (MCP Server) later

### Features

- List all available dimensions/metrics
- Validate if a dimension/metric exists
- Get description, data type, category
- Fuzzy search for typos
- Compatibility checking

### Structure

```
03-dimension-explorer/
├── README.md
├── fetch_metadata.py      # Script to refresh metadata
├── data/
│   ├── dimensions.json    # All dimensions with descriptions
│   └── metrics.json       # All metrics with descriptions
└── explorer.py            # CLI tool (optional)
```

### Tasks

- [ ] Fetch metadata from GA4 Admin API
- [ ] Structure as searchable JSON
- [ ] Create CLI explorer (optional)
- [ ] Document usage

---

## Component 4: Slack Reporter

**Location:** `04-slack-reporter/`

**Goal:** Automated GA4 reports to Slack

### Features

| Report | Schedule | Content |
|--------|----------|---------|
| Daily Summary | 9:00 AM | Users, sessions, top pages |
| Weekly Digest | Monday 9 AM | WoW comparison, trends |
| Anomaly Alert | Real-time | Traffic ±30% from baseline |

### Structure

```
04-slack-reporter/
├── README.md
├── config.yaml            # Schedules, channels, properties
├── reporter.py            # Main service
├── queries/
│   ├── daily_summary.py
│   ├── weekly_digest.py
│   └── anomaly_check.py
├── templates/
│   └── slack_blocks.py    # Slack Block Kit templates
├── requirements.txt
└── Dockerfile             # For deployment
```

### Tasks

- [ ] Create Slack App
- [ ] Build query functions
- [ ] Create Slack message templates
- [ ] Implement scheduler
- [ ] Add Docker deployment
- [ ] Document setup

---

## Component 5: Realtime Watcher (Deferred)

**Location:** `05-realtime-watcher/`

**Goal:** Real-time monitoring snapshots to Slack

**Status:** Deferred — revisit after components 1-4 complete

### Simplified Approach (API-based)

Instead of screenshots:
1. Fetch real-time data via GA4 Real-time API
2. Generate chart image with Plotly/Matplotlib
3. Send to Slack

### Structure (Future)

```
05-realtime-watcher/
├── README.md
├── realtime_api.py        # Fetch real-time data
├── chart_generator.py     # Generate chart images
├── watcher.py             # Main service
└── config.yaml
```

---

## Build Order

```
Phase 1: Foundation
├── [1] MCP Setup ←── START HERE
└── [2] GA Agent Skill (core)

Phase 2: Enhancements
├── [3] Dimension Explorer
└── [4] Slack Reporter

Phase 3: Advanced (Deferred)
└── [5] Realtime Watcher
```

---

## Environment Setup

### Required Credentials

```bash
# Google Cloud
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
GA4_PROPERTY_ID=123456789
BIGQUERY_PROJECT_ID=your-project

# Slack (for Component 4)
SLACK_BOT_TOKEN=xoxb-...
SLACK_CHANNEL_ID=C0123456789
```

### Python Dependencies

```
# Core (Components 1-3)
google-analytics-data>=0.18.0
google-cloud-bigquery>=3.12.0
google-auth>=2.23.0
pandas>=2.0.0

# Visualization
plotly>=5.18.0
jinja2>=3.1.0

# Slack Reporter (Component 4)
slack-sdk>=3.23.0
apscheduler>=3.10.0
pyyaml>=6.0
```

---

## Quick Start

```bash
# Navigate to project
cd /Users/ourdigital/Projects/claude-skills-factory/ga-agent-project

# Start with MCP setup
cat 01-mcp-setup/setup-guide.md
```