Developer Quick Reference & Handover Guide

A comprehensive reference for developers working with or taking over the GP3MixMedia TrailMix platform.

Project Overview

Key Statistics

Directory Structure

gp3mixmedia/
├── gp3mixmedia-web/              # Main application
│   ├── app/                      # Next.js App Router
│   │   ├── api/v1/              # 286 REST API endpoints
│   │   ├── (docs)/docs/         # In-app documentation portal
│   │   ├── campaigns/           # Campaign pages
│   │   ├── ingestion/           # Ingestion pages
│   │   ├── dedupe/              # Deduplication pages
│   │   └── admin/               # Admin pages
│   ├── src/
│   │   ├── workers/             # Background jobs & scheduler
│   │   │   ├── feeds/           # Feed implementations (FCC, AdImpact, Meta, etc.)
│   │   │   ├── mailbox/         # Gmail polling (rep sheets, newsletters)
│   │   │   ├── scheduler/       # Cron job configuration
│   │   │   └── index.ts         # Worker entry point
│   │   └── server/              # Server-side utilities
│   ├── lib/                     # Shared libraries & services
│   │   ├── services/            # Business logic (alerts, dedupe, reconciliation)
│   │   └── vendor/              # External API clients (FCC, OpenFEC)
│   ├── components/              # React UI components
│   ├── prisma/
│   │   ├── schema.prisma        # Database schema (221 models)
│   │   └── migrations/          # 153 schema migrations
│   ├── content/docs/            # In-app documentation (markdown files)
│   ├── tests/                   # Test files (331+ files, Vitest)
│   ├── .env.example             # Complete env var reference
│   ├── Dockerfile               # Multi-stage production build
│   └── fly.toml                 # Fly.io web app config
├── deploy/
│   ├── mysql/                   # MySQL + ProxySQL Docker setup
│   │   ├── Dockerfile           # MySQL 8.0.44 image
│   │   └── fly.toml             # Fly.io DB config
│   └── fly/                     # Deployment helpers
├── docs/                        # Extended documentation
│   ├── api/                     # API docs (auth, pagination, errors)
│   ├── adr/                     # Architecture Decision Records
│   ├── runbooks/                # Incident response procedures
│   └── email-parsing/           # Email parsing system docs
├── fly.toml                     # Fly.io database config
└── README.md                    # Project overview

External Dependencies

Infrastructure Services

Data Source APIs

Communication & Monitoring

Fly.io Architecture

The platform runs as two separate Fly.io apps:

1. Database App (gp3mixmedia)

• Image: Custom MySQL 8.0.44 + ProxySQL
• Region: iad (US East)
• Ports: 3306 (MySQL direct), 6033 (ProxySQL - app should connect here)
• Storage: 8GB persistent volume at /var/lib/mysql
• VM: 8GB RAM, 4 performance CPUs

2. Web App (gp3mixmedia-web)

• Region: iad (US East)
• Processes:
  • web — Next.js server (port 3000, HTTPS enforced)
  • ingest — Background ingestion workers (cron-based feeds, Gmail polling)
  • historical-ingest — Large backfill jobs (auto-suspends when idle)
• VM per process: 8GB RAM, 1-2 performance CPUs
• Deploy: fly deploy runs migrations via release_command
• Health checks: /api/v1/health (45s timeout), /api/v1/ping (10s timeout)

Deployment Commands

# Deploy web app
cd gp3mixmedia-web && fly deploy

# Deploy database
cd deploy/mysql && fly deploy --app gp3mixmedia

# Set secrets (web app)
fly secrets set META_ADS_API_TOKEN=xxx --app gp3mixmedia-web

# SSH into web app
fly ssh console --app gp3mixmedia-web

# View logs
fly logs --app gp3mixmedia-web
fly logs --app gp3mixmedia-web --process ingest

# Scale machines
fly scale count web=1 ingest=1 --app gp3mixmedia-web

Environment Variables

Required Secrets (set via fly secrets set or .env)

These have no defaults and must be provided:

Required for Specific Feeds

Variables with Defaults (override if needed)

Variables Set in the UI (Campaign Settings)

These are configured per-campaign through the web interface, not env vars:

Scheduled Jobs (Crons)

Feed Ingestion Schedules

Background Worker Schedules

Health & Monitoring Schedules

Polling Workers (non-cron)

Meta Ads Library Feed Setup

The Meta Ads Library feed pulls political/issue ads from Facebook and Instagram.

Prerequisites

1. Facebook Developer Account with access to the Ad Library API
2. Facebook Access Token with ads_read permission
   • Go to Meta for Developers
   • Create an app or use an existing one
   • Generate a long-lived access token with ads_read scope
   • The token must belong to an account approved for the Ad Library API

Environment Configuration

Set the access token as a secret:

# On Fly.io
fly secrets set META_ADS_API_TOKEN=your_facebook_access_token --app gp3mixmedia-web

# In .env for local development
META_ADS_API_TOKEN=your_facebook_access_token

The following env vars have sensible defaults but can be overridden:

Campaign-Level Configuration

After the env var is set, configure per-campaign in the UI:

1. Navigate to Campaign Settings > Feeds > Meta Ads Library
2. Configure:
   • Search Terms: Keywords to find relevant ads (leave empty for auto-derive from campaign name/candidates)
   • Advertiser IDs: Optional — specific Meta advertiser page IDs to monitor
   • Geographic Scope: Countries/regions to include

How It Works

1. The feed runs on the META_ADS_CRON schedule (default: every 8 hours)
2. For each campaign with Meta enabled:
   • Uses search terms (configured or auto-derived from campaign candidates)
   • Queries the Meta Ad Library API for political/issue ads matching those terms
   • Applies keyword fallback if primary search returns few results
   • Converts matching ads to buy line candidates
   • Runs deduplication against existing records
3. Circuit breaker protects against API failures with exponential backoff
4. Partial results are saved on timeouts (graceful degradation)

Key Files

• Feed implementation: src/workers/feeds/meta-ads-library.ts
• API client: lib/services/social-creative/meta-ads-library.client.ts

Local Development Setup

Prerequisites

• Node.js 22.14.0+ (use nvm or fnm)
• MySQL 8+ (local or Docker)
• Redis (optional for dev — falls back to in-memory)

Quick Start

# 1. Clone and install
git clone <repo-url> && cd gp3mixmedia/gp3mixmedia-web
npm install

# 2. Set up environment
cp .env.example .env
# Edit .env with your DATABASE_URL, auth secrets, etc.

# 3. Set up database
npx prisma migrate deploy    # Apply all migrations
npx prisma generate          # Generate Prisma client

# 4. Start development
npm run dev                  # Next.js dev server on :3000

# 5. Start workers (separate terminal)
npm run ingest               # Background workers

Common Commands

# Development
npm run dev                     # Start dev server
npm run ingest                  # Start ingestion workers
npm run build                   # Production build
npm start                       # Production server

# Database
npx prisma migrate deploy      # Apply migrations
npx prisma migrate dev          # Create new migration
npx prisma studio               # Visual database browser
npx prisma generate             # Regenerate client after schema changes

# Testing
npm test                        # Run all tests (Vitest)
npm run test:watch              # Watch mode
npm run build                   # Verify no build errors (important for circular deps)

# Gmail Label Discovery
npx tsx src/workers/mailbox/label-utils.ts   # List Gmail label IDs

# Deployment
fly deploy --app gp3mixmedia-web             # Deploy web app
fly secrets set KEY=VALUE --app gp3mixmedia-web  # Set secrets

API Endpoints Quick Reference

Core

GET/POST   /api/v1/campaigns
GET/PATCH  /api/v1/campaigns/{id}
POST       /api/v1/campaigns/{id}/clone

Matrix

GET        /api/v1/matrix
POST       /api/v1/matrix/batch-update
GET        /api/v1/matrix/export

Deduplication

GET        /api/v1/dedupe/groups
POST       /api/v1/dedupe/groups/{id}/resolve
POST       /api/v1/dedupe/rows/combine

Ingestion

GET/POST   /api/v1/ingestion/control
POST       /api/v1/aide/inbound          # AIDE webhook endpoint

Email & Notifications

POST       /api/v1/email/send
GET        /api/v1/email/logs
POST       /api/v1/push/subscribe
POST       /api/v1/push/send

Health & Monitoring

GET        /api/v1/ping                  # Liveness check
GET        /api/v1/health                # Full health check
GET        /api/v1/observability/metrics  # Prometheus metrics
GET        /api/v1/circuit-breakers       # Circuit breaker status

Interactive API Docs

• Swagger UI: /api/docs
• OpenAPI Spec: /api/v1/openapi.json

Key Design Patterns

Circular Dependency Prevention

Next.js builds can fail with ReferenceError: Cannot access 'X' before initialization due to circular imports. Always use dynamic imports in API route files for service/worker modules:

// WRONG — static import causes TDZ errors
import { someService } from '@/lib/services/some-service';

// RIGHT — dynamic import breaks circular chain
async function getSomeService() {
  const { someService } = await import('@/lib/services/some-service');
  return someService;
}

Soft Deletes

High-value tables use soft deletes (archived, not deleted). Data can always be recovered from the archives.

Feed Distributed Locks

Redis-based locks prevent duplicate feed runs across processes. Lock TTL defaults to 2700s with 60s heartbeat.

Circuit Breaker

External API calls use circuit breakers for resilience. Status viewable at /api/v1/circuit-breakers.

Quick Troubleshooting

Security Features

• Google Workspace SSO (NextAuth.js)
• Role-based access control (Viewer, Analyst, Admin) with per-campaign permissions
• CSRF protection with signed tokens
• Optional 2FA (TOTP authenticator apps)
• API rate limiting via Upstash Redis (configurable per tier)
• Request idempotency to prevent duplicate processing
• Soft-delete with recovery on all high-value data
• AES-256-GCM encryption for stored API tokens
• Comprehensive audit trails
• Sentry error tracking and alerting
• Circuit breaker pattern for external API resilience

Monitoring Endpoints

Last Updated: March 2026