Media Kits and Rosters — System Architecture

Last updated: 2026-04-06

1. Purpose and Users

The Media Kits and Rosters app is the public-facing surface for our creator roster and the internal tool agents use to assemble curated lineups for brands.

It supports three main jobs:

• give brands clean, consistent media kits for each creator,
• let agents build rosters and share them as simple links,
• keep creator data, headshots, and featured videos in sync with Airtable and ca-data.

Primary users: agents, TAs, Apple, and external brand partners who receive roster links.

2. URLs and Access

• Primary domain: https://rosters.creatorsagency.co
• Legacy Vercel URL: https://creator-media-kits-app.vercel.app (do not use in links)
• Repo: partnerships-collabs/creator-media-kits-app

Key routes:

• /[creator-slug] – individual media kits,
• /roster – internal roster builder (auth restricted to @creatorsagency.co),
• /roster/[category] – public category rosters,
• /r?creators=slug1,slug2&brand=Brand – shareable roster view for brands.

3. High-Level Architecture

Frontend

• Next.js on Vercel, using the CA design system (dark theme, CA coral).

Data source: ca-data

• Creator records live in Airtable and sync into ca-data.
• Media kits read creator data from ca-data through a proxy in the Next.js app.
• Critical env vars on Vercel:
  • CA_DATA_URL,
  • CA_DATA_TOKEN.

Mini worker and cron layer

• Mac Mini hosts helper scripts that:
  • pull creator updates from Airtable into ca-data,
  • download and commit headshots,
  • refresh featured videos,
  • write media kit URLs back into Airtable.
• Mini also runs a webhook server for:
  • Fathom transcripts,
  • brand logo fetching and caching.

4. Data Flow

4.1 Creator records

1. Airtable is the source of truth for creator roster fields:
   • name, slug, channels,
   • platform stats and averages,
   • demographics,
   • creator type and do-not-pitch flags,
   • brand partnerships and similar creators.
2. Mini cron jobs pull Airtable and update ca-data every few hours.
3. ca-data exposes GET /creators and GET /creators/:slug.
4. The media kits app calls ca-data on each request to render creator pages and the roster grid.

If ca-data is unavailable, media kits cannot load core creator data.

4.2 Headshots and media kit URLs

• Headshots are downloaded to the repo on Mini and committed to git.
• A weekly Mini cron runs a sync_and_deploy script that:
  • pulls new creator rows from Airtable,
  • skips any creator with no headshot,
  • commits updated headshots and JSON,
  • pushes to GitHub so Vercel can deploy.
• As part of this sync, the script writes each creator's media kit URL (rosters.creatorsagency.co/{slug}) back into Airtable when missing.

Rules:

• Every live creator must have a headshot or they will not appear on the site.
• Always use rosters.creatorsagency.co links in comms, not the raw Vercel URL.

4.3 Do-not-pitch handling

• Airtable Creator Type and related fields control visibility.
• Roster builder filters out do-not-pitch creators entirely.
• Individual media kit pages return 404 for do-not-pitch creators.

This makes it safe to share roster URLs with brands without exposing excluded creators.

4.4 Featured videos

Featured videos for each creator are driven by ca-data:

• ca-data sync scripts fetch videos from YouTube, Instagram, TikTok, and Monday links and store them in a videos table ordered by views.
• The media kits app calls ca-data /videos endpoints when rendering a creator page.
• Platform-specific rules decide how many videos to show and which platform to favor.

A monthly Mini cron calls the ca-data sync for each creator to refresh view counts and selection.

4.5 Brand partnerships and similar creators

• Brand partnership cards on a media kit use structured fields from ca-data (ultimately sourced from Monday and Airtable).
• Only partnerships with a usable videoUrl are rendered.
• Similar creators are drawn from Airtable fields and surfaced in the media kit layout.

4.6 Rosters and vanity URLs

Rosters are saved server-side and shared as short links.

Flow:

1. Agent builds a lineup on /roster and adds a brand name.
2. The app generates a default slug such as nike-mar-26 that can be edited.
3. On Save, the app writes roster metadata to Vercel Blob storage with that slug.
4. The final share URL looks like https://rosters.creatorsagency.co/r/{slug}.

Rules:

• Slugs are unique. If a slug is taken, the app appends -2, -3, and so on.
• The slug locks the creator lineup and order. Stats and rates stay live from Airtable.
• Save and Copy confirms a successful write and copies the link.

5. Deployment and Environments

• Source of truth: partnerships-collabs/creator-media-kits-app on GitHub.
• Deploy pattern: push to GitHub and let Vercel auto-deploy.
• Do not run vercel --prod from local clones.

Environments:

• Production: rosters.creatorsagency.co
• Mini: /Users/ari/code/creator-media-kits-app/ for day-to-day development.

When updating env vars (API keys, ca-data URL, Rapid API keys for videos), update Vercel project settings and redeploy.

6. Common Ops and Dev Tasks

6.1 Add or update a creator

1. Update the creator record in Airtable, including:
   • headshot attachment,
   • platform links and stats,
   • demographics,
   • creator type.
2. Wait for the next Mini sync (or run the sync script manually if you are on Mini).
3. Verify on:
   • /roster grid,
   • /[creator-slug] media kit page.

If the creator does not appear, check for:

• missing headshot,
• creator type marked as do-not-pitch,
• ca-data sync errors.

6.2 Fix a bad or missing featured video

1. Confirm the right video links exist in Airtable or Monday for the creator.
2. Trigger ca-data featured video sync for that creator from Mini.
3. Wait for the next deploy if the frontend schema changed.
4. Reload the creator media kit.

6.3 Update design or copy

Safe changes:

• text on labels and section headers,
• stat layout and typography,
• which fields are visible in the roster CSV export.

Higher risk changes that require coordination:

• any change that alters which creators appear for a brand by default,
• changes to do-not-pitch logic,
• changes that alter how many videos or partnerships are shown.

6.4 Handle outages

If media kits or rosters are failing in production:

1. Load a simple media kit page and /roster.
2. If the shell loads but data is empty, check ca-data health.
3. If images or headshots are missing, check the last Mini sync and git history.
4. If roster save or fetch fails, inspect Vercel Blob configuration and recent deploys.

7. How other agents and skills should use Media Kits

Human agents and TAs

• Use /roster as the default place to build and save branded lineups; do not hand-build creator lists in spreadsheets when the same set exists here.
• Share only rosters.creatorsagency.co/r/{slug} links with brands so you get versioned lineups with live stats.
• When evaluating a single creator, use their media kit page (/[slug]) instead of raw Airtable rows; it shows featured videos, partnerships, and similar creators in one place.

Automation and internal agents

• Treat media kits and rosters as the presentation layer over Airtable + ca-data:
  • Any script or agent that needs creator data should read from ca-data (/creators, /videos, brand-partnership tables), not scrape HTML from rosters.
  • Never auto-create or auto-delete roster slugs; that stays a human action from /roster.
• When generating outbound materials (one-pagers, proposal inputs), link back to:
  • individual media kits for deep dives on a creator,
  • saved roster URLs when referencing a lineup.
• If a skill detects missing data (blank headshot, empty featured videos), it should log a handoff rather than guessing or silently skipping the creator.

8. Related Docs

• memory/project-media-kits.md for full technical history and open items.
• docs/creator-media-kits-project.md for older architecture notes.
• memory/infrastructure.md under "Creator Media Kits App Deploy" for deploy lessons.
• docs/creators-agency/creators.md for strategic creator segmentation.