SponsorGraph AI - Claude Code Project

Complete Claude Code setup with iterative learning, real industry data, and production-grade patterns

Brand Positioning (Web v1)

Core promise: Turn creator partnerships into forecastable growth.
Experience model: Brand-first, progressive-trust onboarding (explore planner → compare scenarios → request pilot outline).
Proof model: Strict separation between synthetic_modeled planning views and verified_real partner outcomes.

Top-Level Website IA

Overview: narrative entry, trust framing, and soft conversion path
Demo: guided synthetic scenario planner with provenance/source visibility
Case Studies: consent-gated proof narratives
Results: verified KPI/testimonial surfaces
For Brands: pilot planning path
For Creators: benchmark and sponsor-readiness path

📁 Project Structure

sponsorgraph_project/
├── .claude/                          # Claude Code configuration
│   ├── CLAUDE.md                     # Main project context
│   ├── business_logic.md             # Real industry benchmarks (12K+ campaigns)
│   ├── settings.json                 # Hooks, MCPs, permissions
│   │
│   ├── skills/                       # Reusable patterns
│   │   ├── bigquery/SKILL.md         # BigQuery optimization patterns
│   │   ├── dbt/SKILL.md              # dbt transformation patterns
│   │   ├── ml-pipeline/SKILL.md      # ML model training patterns
│   │   └── api-design/SKILL.md       # FastAPI endpoint patterns
│   │
│   ├── agents/                       # Specialized sub-agents
│   │   ├── data-engineer/AGENT.md    # dbt + BigQuery specialist
│   │   ├── ml-engineer/AGENT.md      # Vertex AI + model training
│   │   └── frontend-engineer/AGENT.md # React + dashboard specialist
│   │
│   ├── workflows/                    # Step-by-step guides
│   │   ├── add-platform.md           # Add new social platform
│   │   ├── new-attribution-model.md  # Implement attribution logic
│   │   ├── deploy-model.md           # Deploy ML model to Vertex AI
│   │   └── synthetic-case-study.md   # Build synthetic demo case studies
│   │
│   ├── context/                      # Additional docs
│   │   ├── api-design.md             # REST API conventions
│   │   ├── data-quality.md           # Data validation rules
│   │   └── testing-strategy.md       # Test coverage requirements
│   │
│   ├── hooks/                        # Iterative learning system
│   │   ├── on_error.py               # Auto-log errors
│   │   ├── on_success.py             # Auto-log solutions
│   │   ├── pre_tool_use.py           # Validate before tool use
│   │   └── post_tool_use.py          # Update docs after success
│   │
│   └── docs/                         # Learning logs
│       ├── errors.md                 # Error catalog (auto-updated)
│       ├── solutions.md              # Solutions catalog (auto-updated)
│       └── improvements.md           # Continuous improvement log
│
├── src/
│   ├── ingestion/                    # Platform API clients
│   ├── dbt/                          # Data transformations
│   ├── ml/                           # Model training
│   ├── api/                          # FastAPI backend
│   └── frontend/                     # React dashboard
│
└── README.md                         # This file

🚀 Quick Start

1. Install Claude Code

# macOS/Linux
curl -fsSL https://claude.ai/install.sh | bash

# Or via Homebrew
brew install claude-code

2. Initialize Project

cd sponsorgraph_project
claude

# Claude will automatically load .claude/CLAUDE.md on startup

3. Verify Setup

# Inside Claude Code session
> /permissions  # Check tool permissions
> /skills       # View available skills
> /agents       # List specialized agents

💡 Key Features

1. Iterative Learning System

Claude learns from mistakes and successes:

Error Logging: Errors automatically logged to .claude/docs/errors.md
Solution Catalog: Successful patterns saved to .claude/docs/solutions.md
Continuous Improvement: After each task, Claude reviews if pattern is reusable

How it works:

1. Claude encounters error → OnError hook logs to errors.md
2. Claude solves problem → OnSuccess hook prompts to document
3. Next session → Claude reads errors.md and solutions.md
4. Result: Claude remembers and improves over time

2. Real Industry Data

No arbitrary numbers. All metrics based on actual 2024-2025 data:

12,000+ real creator campaigns (CreatorsJet 2025)
Platform CPMs: YouTube ($5.70), TikTok ($6.50), Instagram ($6.59)
Conversion rates: 2% CTR, 2% CVR (vs 0.8% for ads)
Pricing tiers: Nano ($20-200) to Mega ($15K-200K)

See .claude/business_logic.md for complete benchmarks.

3. Specialized Agents

Invoke expert agents for specific tasks:

# Data engineering tasks
> /agent data-engineer "optimize this slow query"

# ML model training
> /agent ml-engineer "train pricing model with new features"

# Frontend work
> /agent frontend-engineer "add TikTok platform to dashboard"

4. Reusable Skills

Skills are automatically activated based on context:

BigQuery Skill: Triggers when writing SQL, designing schemas
dbt Skill: Triggers when working with transformations
ML Pipeline Skill: Triggers when training models
API Design Skill: Triggers when building endpoints

5. Step-by-Step Workflows

Comprehensive guides for common tasks:

# Add new platform (Instagram, TikTok, etc.)
> View .claude/workflows/add-platform.md

# Implement new attribution model
> View .claude/workflows/new-attribution-model.md

# Deploy ML model
> View .claude/workflows/deploy-model.md

# Build synthetic case-study pipeline
> View .claude/workflows/synthetic-case-study.md

🧠 How Claude Learns

Error → Solution → Skill Pipeline

1. ❌ Error occurs
   └─> Auto-logged to errors.md with context

2. 🔍 Claude debugs
   └─> Finds root cause
   └─> Implements fix

3. ✅ Solution works
   └─> Logged to solutions.md
   └─> Reviewed for reusability

4. 📚 Pattern emerges
   └─> Extracted to skill or workflow
   └─> Available in future sessions

5. 🔄 Continuous improvement
   └─> Claude gets better over time
   └─> Team shares accumulated knowledge

Example Learning Cycle

Session 1: Claude encounters BigQuery query timeout

Error logged: "Query exceeded resource limits"
Root cause: Missing partition filter
Solution: Added WHERE date >= '2024-01-01'

Session 2: Similar query needed

Claude reads solutions.md
Automatically adds partition filter
No error, faster query

Session 3: Pattern crystallizes

Added to BigQuery skill
Now applies to all partitioned queries
Team benefits from lesson learned

📊 Business Logic Integration

Where Numbers Come From

All pricing, CPMs, conversion rates sourced from:

CreatorsJet - 12,000 real campaign analysis
Aspire - State of Influencer Marketing 2025
Gupta Media - Real-time CPM tracker
eMarketer - YouTube CPM data
Quimby Digital - Platform comparisons

Never Make Up Numbers

# ❌ BAD: Arbitrary numbers
creator_rate = 5000  # Where did this come from?

# ✅ GOOD: Use real benchmarks
from business_logic import MICRO_RATES
creator_rate = MICRO_RATES["instagram_post"]["median"]  # $500

All benchmarks in .claude/business_logic.md with sources and dates.

🛠️ Development Standards

Code Style

# Python: Black, isort, pylint
# Type hints required
def calculate_attribution(
    touchpoints: List[Touchpoint],
    model: AttributionModel = AttributionModel.DATA_DRIVEN
) -> Dict[str, float]:
    """Calculate attribution weights for touchpoints"""
    ...

Testing Requirements

# Unit tests: ≥80% coverage
pytest tests/ --cov=src --cov-report=term

# dbt tests: Required on all models
cd src/dbt && dbt test

# API + synthetic + ingestion test suites
pytest -q

Git Workflow

# Branch naming
feature/add-tiktok-integration
fix/attribution-query-timeout
refactor/optimize-bigquery-costs

# Commit messages (Conventional Commits)
feat: add Instagram Graph API client
fix: handle rate limits in YouTube ingestion
refactor: optimize attribution query performance

🔐 Security

API Keys

# NEVER commit keys
echo ".env" >> .gitignore
echo "*.key" >> .gitignore

# Use environment variables
export YOUTUBE_API_KEY="your_key"

# Or GCP Secret Manager
gcloud secrets create youtube-api-key --data-file=key.txt

BigQuery Cost Control

# Always dry-run expensive queries
from claude.skills.bigquery import safe_query

df = safe_query(sql, max_gb=1.0)  # Blocks if >1GB scan

📝 Common Commands

# One-shot pre-production checks (recommended)
./scripts/preprod_checks.sh

# Development
uvicorn src.api.main:app --reload                 # Start API server
npm run dev --prefix src/frontend                 # Start frontend
python3 src/synthetic/generate_cases.py           # Regenerate synthetic snapshot + seeds

# Data operations
cd src/dbt && dbt deps                             # Install dbt packages
cd src/dbt && dbt seed --select synthetic_creator_profiles synthetic_content_events synthetic_touchpoints synthetic_campaign_costs synthetic_conversions
cd src/dbt && dbt run --select stg_synthetic__creator_profiles stg_synthetic__content_events stg_synthetic__touchpoints stg_synthetic__campaign_costs stg_synthetic__conversions dim_creator fact_content_performance fact_touchpoints fact_conversions fact_campaign_forecast
cd src/dbt && dbt test --select stg_synthetic__creator_profiles stg_synthetic__content_events stg_synthetic__touchpoints stg_synthetic__campaign_costs stg_synthetic__conversions fact_touchpoints fact_conversions fact_campaign_forecast

# Frontend quality checks
npm run -s type-check --prefix src/frontend
npm run -s build --prefix src/frontend

# Python test suites
pytest -q

# Claude Code
/skills                           # List available skills
/agents                           # List specialized agents
/memory                           # View/edit persistent memory
/permissions                      # Manage tool permissions

🎯 Next Steps

For New Contributors

Read CLAUDE.md: Understand project context
Review business_logic.md: Learn industry benchmarks
Install deps: pip install -r requirements.txt -r requirements-dev.txt and npm ci --prefix src/frontend
Run quality gates: ./scripts/preprod_checks.sh
Start coding: Claude will guide you with skills + workflows

For Claude Code

# On first startup in project
> /init  # Generate project orientation (already done)

# During development
> "Help me add LinkedIn as a new platform"
# Claude will:
# 1. Read workflow: .claude/workflows/add-platform.md
# 2. Activate skills: bigquery, dbt, api-design
# 3. Follow step-by-step guide
# 4. Log any errors/solutions

📚 Additional Resources

🤝 Contributing

Check .claude/docs/errors.md for known issues
Search .claude/docs/solutions.md for patterns
Follow workflows in .claude/workflows/
Update docs after solving problems
Share learnings with team

📄 License

MIT License - See LICENSE file

🙏 Acknowledgments

Built with:

Claude Code by Anthropic
Real industry data from 12,000+ creator campaigns
Iterative learning patterns for continuous improvement
Production-grade data engineering practices

Version: 1.0.0
Last Updated: 2026-02-07
Model: Claude Opus 4.5

Synthetic Case Study Demo (Golf Trio)

SponsorGraph now includes a deterministic synthetic demo system for brand-first planning across three creator tiers.

What was added

Synthetic generator config: configs/synthetic_cases.yaml
Generated snapshot for API: configs/synthetic_cases_snapshot.json
Generated raw seed tables: src/dbt/seed/synthetic/*.csv
API endpoints:
- GET /api/v1/synthetic/cases
- GET /api/v1/synthetic/cases/{case_id}
- GET /api/v1/synthetic/assumptions
- POST /api/v1/synthetic/forecast
Frontend Demo tab now calls synthetic APIs with:
- tier selection
- objective selector
- package mode toggle (platform-specific vs cross-platform bundle)
- budget input
- provenance and source references on KPI surfaces

Regenerate demo data

python3 src/synthetic/generate_cases.py

Validate locally

pytest tests/synthetic tests/api -q
cd src/frontend && npm run type-check

Provenance policy

Synthetic demo outputs must include:

provenance: public_real | synthetic_modeled | verified_real
source_ref: source URL + retrieval date for surfaced benchmark metrics

Use synthetic metrics for planning only until partner-verified data is connected.

Lead capture flow

Landing pages now submit inquiries through POST /api/v1/leads with validated payloads and source attribution (for-brands, for-creators, etc.).

Captured leads are persisted locally to:

.claude/runtime/leads.ndjson

Set a custom storage path with:

export LEAD_STORAGE_PATH=/path/to/leads.ndjson

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.claude		.claude
.github/workflows		.github/workflows
configs		configs
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
README.md		README.md
pytest.ini		pytest.ini
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

SponsorGraph AI - Claude Code Project

Brand Positioning (Web v1)

Top-Level Website IA

📁 Project Structure

🚀 Quick Start

1. Install Claude Code

2. Initialize Project

3. Verify Setup

💡 Key Features

1. Iterative Learning System

2. Real Industry Data

3. Specialized Agents

4. Reusable Skills

5. Step-by-Step Workflows

🧠 How Claude Learns

Error → Solution → Skill Pipeline

Example Learning Cycle

📊 Business Logic Integration

Where Numbers Come From

Never Make Up Numbers

🛠️ Development Standards

Code Style

Testing Requirements

Git Workflow

🔐 Security

API Keys

BigQuery Cost Control

📝 Common Commands

🎯 Next Steps

For New Contributors

For Claude Code

📚 Additional Resources

🤝 Contributing

📄 License

🙏 Acknowledgments

Synthetic Case Study Demo (Golf Trio)

What was added

Regenerate demo data

Validate locally

Provenance policy

Lead capture flow

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages