Creators Agency Docs

Brand Match App — System & Ops ​

Last updated: 2026-04-06

1. Purpose and Users ​

Brand Match is the internal web app agents use to:

  • find the best creators for a brand,
  • see recent brand activity and past integrations,
  • manage agent ownership for brands,
  • spot cross-sell and category gap opportunities.

Primary users: Annie, Charlie, Henry and other brand-facing sellers.

2. URLs and Access ​

  • Production: https://brand-match-app.vercel.app
  • Mini (internal only): http://100.104.197.44:3000
  • Repo: partnerships-collabs/brand-match-app

Auth is handled by Vercel. The app is internal only and should not be shared as a public link with brands.

3. High-Level Architecture ​

Frontend

  • Next.js App Router, TypeScript, Tailwind.
  • Deployed on Vercel under the creators-agency1 team.

Backend data source

  • All core data now comes from ca-data at https://ca-data.vercel.app.
  • Brand Match never reads local JSON files for matches or brand intel any longer.

ca-data is a Node/Express API backed by Neon Postgres. It aggregates:

  • Airtable creator roster (headshots, niches, demo data),
  • Close CRM deals for spend and deal count,
  • Monday deliverables for integrations and CPM math,
  • Fathom call summaries,
  • Email summaries from Close and Gmail,
  • Brand match tables (v3 scoring output and enrichment files).

Brand Match talks to ca-data through a small set of API routes in the Next.js app. These use Vercel env vars:

  • CA_DATA_URL for the base URL,
  • CA_DATA_TOKEN for bearer auth.

Key point: ca-data is a single point of failure for Brand Match. If Brand Match pages stop loading data, check ca-data first.

4. Data Model and Flow ​

4.1 Matches and scoring ​

  • All creator–brand match rows live in a Neon table inside ca-data.
  • The v3 scoring pipeline is a Python batch job that writes scores and components back to Neon.
  • Brand Match reads matches by brand or creator, not by scanning one giant JSON blob.

Signals in v3 scoring (summarized):

  • Brand behavioral fit,
  • Niche precision,
  • Competitive context (currently flat),
  • Price versus market,
  • Audience demographics,
  • Inventory and momentum.

Matches are exposed by ca-data endpoints such as:

  • GET /matches?brand=BrandName,
  • GET /matches?creator=CreatorSlug.

The app never edits matches directly. Any change to scoring or assignments happens through ca-data scripts.

4.2 Brand intel ​

Brand intel for cards and detail views is assembled in ca-data and exposed through:

  • GET /brand-intel for available brands and filters,
  • GET /brand-intel/:slug for full detail.

Inputs that roll into brand intel:

  • Close CRM won and active deals (total deals, average rate),
  • Monday deliverables (integration counts and CPM),
  • Brand activity dates (last integration date),
  • Contact history (last contacted date and agent),
  • Email summaries for the most recent outbound threads,
  • Website and contact info.

Brand Match uses this to power:

  • Available brands table and filters (last activity, last contact, actively spending),
  • Brand overview cards (average rate, average CPM, number of past deals),
  • "Last Email" and contact context sections.

4.3 Creator and roster data ​

Creator profiles in Brand Match are lightweight mirrors of the master creator roster that lives in Airtable and is synced into ca-data.

  • ca-data exposes GET /creators and creator detail endpoints.
  • Brand Match uses these to render creator profile pages and to enrich match cards with:
    • headshot,
    • channel links,
    • niche and topics,
    • audience demo summary.

4.4 Conflicts and past comms ​

Brand Match also surfaces risk and context signals:

  • Conflict database for creators with active sponsors that might conflict with a new brand.
  • Fathom call summaries for past meetings with the brand (via ca-data Fathom sync).
  • Brand email summaries from Close and Gmail.

These are all written into Neon by ca-data sync scripts and read through the /brand-intel and /conflicts style endpoints.

5. Key Pages and What They Depend On ​

5.1 /brands/available ​

Purpose: show unclaimed or under-worked brands ranked by opportunity.

Data pulled from ca-data:

  • Brand intel table for:
    • last activity date,
    • last contacted date,
    • last contact agent and subject,
    • last contact summary,
    • website.
  • Filters use these dates to drive views such as "Actively spending" and "Never contacted".

If this page shows blank or errors, likely causes:

  • ca-data unavailable or returning 500,
  • CA_DATA_URL or CA_DATA_TOKEN misconfigured in Vercel.

5.2 /brands/available/[slug] and /brand/[slug] ​

Purpose: deep dive on a single brand.

Dependencies:

  • Brand intel row for that brand,
  • Matches table for top matched creators,
  • Deal history from Close and Monday,
  • Brand email summaries from ca-data brand_emails table,
  • Optional Fathom calls for that brand.

The page shows:

  • headline stats (average rate, CPM, deals),
  • creators they have worked with and how often,
  • top matched creators with v3 scores and narratives,
  • latest email thread summary and contact info.

5.3 /creator/[slug] ​

Purpose: show all brands that are a good fit for a creator and how those brands behave.

Dependencies:

  • Creator detail from ca-data,
  • Matches table filtered by creator,
  • Brand intel for each matched brand.

This is the reverse view of Brand Match. It is useful for planning outbound around a specific creator or pod.

5.4 Other analytic views ​

Other routes (cross-sell, reverse-match, contract-lifecycle, category-gaps, agent-blind-spots) are all thin frontends over ca-data summary tables. The logic lives mostly in ca-data sync scripts and SQL, not in Brand Match itself.

6. Deployment and Environments ​

  • Source of truth: partnerships-collabs/brand-match-app on GitHub.
  • Deploy pattern: push to GitHub and let Vercel auto-deploy.
  • Never run vercel --prod locally.

Environment configuration that matters:

  • CA_DATA_URL and CA_DATA_TOKEN must match the active ca-data deployment.
  • Any new ca-data endpoint used by Brand Match must be added to Vercel env before deploy.

Mini runs a local copy of the app at http://100.104.197.44:3000 for debugging and work-in-progress changes before pushing.

7. Common Ops and Dev Tasks ​

7.1 Refresh scoring or match data ​

When match quality changes or new brands need to be scored:

  1. Update scoring logic or inputs in the ca-data repo.
  2. Run the v3 scoring batch script to recompute scores and write them to Neon.
  3. Verify spot checks through ca-data endpoints (/matches, /brand-intel).
  4. Confirm Brand Match reflects changes on:
    • /brands/available,
    • brand detail pages,
    • creator pages.

Brand Match itself does not need a redeploy for pure data updates; it reads live from ca-data.

7.2 Adding new intel fields ​

If you add new columns to brand intel or new derived tables in ca-data:

  1. Add the field to ca-data sync scripts and API responses.
  2. Extend the Brand Match API proxy and page components to read and display the new field.
  3. Keep this doc and memory/project-brand-match.md in sync with any new dependencies.

7.3 Handling outages ​

If Brand Match is failing in production:

  1. Load a simple page such as /brands/available.
  2. If the page shell renders but data is empty, check ca-data:
    • Hit https://ca-data.vercel.app/health or a simple endpoint.
    • Confirm Neon is reachable from ca-data.
  3. If pages do not render at all, check Vercel build logs for brand-match-app.
  4. Only after confirming status, decide whether to roll back to a previous commit or pause new deploys.

7.4 Safe changes for agents and TAs ​

Changes that are safe for agents and TAs to request without a full architecture review:

  • Copy tweaks in headings or labels,
  • New filters or sort orders that use existing data fields,
  • Visual updates on cards and tables.

Changes that require coordination with Apple and Jude:

  • Any change to scoring logic or the source tables in ca-data,
  • New data sources for brand intel (new CRM fields, new external APIs),
  • Changes that can move large sets of brands or creators between agents.

8. How other agents and skills should use Brand Match ​

Human agents (Annie, Charlie, Henry, Apple, TAs)

  • Treat /brands/available as the starting point for new outbound. Use the filters (activity, last contact, agent ownership) instead of building your own brand lists from spreadsheets.
  • When preparing a sprint around a specific creator, start from /creator/[slug] to see which brands already fit and how those brands behave.
  • Use the brand detail view as the single place to check: past deals, average rate/CPM, last email, and past Fathom calls before you write a proposal or email.

Automation and internal agents

  • Sales Enablement Agent and similar skills should treat Brand Match and ca-data as read-only context:
    • Use ca-data endpoints (/matches, /brand-intel, /creators) or the brand-creator-matcher pipeline rather than scraping the Brand Match UI.
    • Never write directly to the matches tables or re-score creators; all scoring changes should flow through the v3 Python scorer described in memory/project-brand-match.md.
  • When producing sales materials (brand reports, proposal inputs), reference:
    • Brand-level stats from ca-data brand intel (deals, average rate/CPM, last contact),
    • Top matched creators and their narratives from the v3 scoring tables.
  • If an internal agent sees blank data where Brand Match normally shows intel, it should:
    1. check ca-data health, 2) log an internal handoff, and 3) avoid making assumptions or fabricating numbers.

9. Related Docs ​

  • memory/project-brand-match.md for detailed dev history and script names.
  • docs/creators-agency/brands.md for high-upside brand strategy.
  • docs/creators-agency/agents/sales-enablement-agent-playbook.md for how agent skills should use Brand Match output.