Athlete-Brand Matching

What it does

athlete-brand-matching is a bundled pilot module for the sport-marketing workflow: athlete intake, brand matching, and first outreach preparation. It is an isolated surface, deliberately separate from the core CRM — it never writes to Mandanten/CRM, contact, sales, or task tables. Matching, follow-up planning, and acquisition state all live inside the module; only outreach emails leave it, as regular email_drafts records.

How to open and enable

• The module ships in bundled-modules/athlete-brand-matching/ (manifest module.json, slug athlete-brand-matching, entry index.html, backend api/handler.mjs, renderer iframe, store categories marketing and insights).
• It is a normal (non-fixed) bundled module: an admin activates it from Module Store, after which it opens at /modules/athlete-brand-matching.
• New pilot instances start empty — there are no bundled demo records. The setup state offers manual capture plus CSV/JSON import CTAs.

Key workflows

1. Capture or import athletes and brands. Athlete profiles hold sport, reach, audience, location, positioning, editable tags, contact, target industries, sponsorship type, status, and custom properties. Brand profiles hold industry, audience, region, editable tags, contact, notes, sponsorship history, custom properties, a module-local acquisition status, rejection reason, last contact date, next follow-up date, and acquisition notes/history. CSV imports use the first row as headers and support common fields such as name, sport, reach, audience, location, tags, email, industry, region, and notes; JSON imports can be an array or an object with athletes, brands, or items.
2. Review imports. Extracted athlete and brand candidates land in a confidence-based review queue before they become profiles.
3. Match. The MVP matching score combines structured tags, industry fit, audience overlap, and region, with a visible "Warum dieser Match?" explanation per recommendation.
4. Prepare outreach. Each match offers an Outreach vorbereiten action that opens an editable outreach modal with athlete, brand, and match-reason context. When a brand is being recontacted, the draft context also includes last contact date, rejection reason, and acquisition notes. Confirming creates a real email draft through the shared /api/drafts endpoint; users can open the draft in the E-Mail Entwürfe screen for review or explicitly send it from the module through the existing draft send endpoint (/api/drafts/:id/send). Automatic background sending is out of scope.
5. Run the acquisition cycle. Brand contacts move through the module-local statuses neu, angesprochen, interessiert, abgesagt, wiedervorlage, and gewonnen. A due-follow-up view lists planned brand recontacts for today, this week, or all.

How the agent can drive it

There are no dedicated athlete_brand_* agent tools. Instead, the iframe posts module page context to Clapilot (via postMessage) with the active view, selected athlete, selected brand, selected brand acquisition context, athlete count, brand count, due follow-up count, review queue count, and outreach draft count. This gives chat/live agents enough page awareness to discuss the active workflow and draft recontact outreach with the last-contact and rejection context — without giving the pilot module access to unrelated customer records. Outreach drafts themselves are normal email drafts, so the standard draft/email tools apply to them once created.

Configuration & limits

• State API: the only module endpoint is /api/modules/athlete-brand-matching/api/state (GET reads, PUT/POST writes; other paths return 404). Responses report persistence: "module-file".
• Storage: the handler persists one JSON file per user below .clapilotaicore/module-state/athlete-brand-matching/<userId>.json. The normalized state shape covers athletes[], brands[], reviewQueue[], outreachDrafts[], followUpTasks[], customFields[], and the current selections; profiles carry the local athlete.profile, brand.profile, brand.acquisition, tags[], and computed match_reasons[] used by the UI. brand.acquisition keeps the acquisition status, rejection reason, last contact date, next follow-up date, notes, and a lightweight history for long-running recontact cycles, plus match_id, generated outreach_draft, match reason, and module-local follow-up references for conversion tracking.
• Browser cache: localStorage is retained only as a migration/offline fallback when the module API is temporarily unavailable.
• Boundaries: follow-up planning stays inside the module state instead of creating global Aufgaben or CRM records. Microsoft account import, crawler-based brand discovery, calendar scheduling, and document contract generation remain follow-up integration work.
• UI: the iframe UI follows the shared Clapilot style guide (outlined white/neutral surfaces, compact outlined list rows, navy primary actions, soft bordered fields, segmented navigation). Module-specific colors are reserved for semantic states such as confidence warnings and fit indicators.

Troubleshooting

• Data seems to disappear or reset: check that the module API is reachable; when it is down the UI falls back to the browser localStorage cache, which is per-browser and not shared.
• Imported rows are missing fields: CSV import maps only the supported header names listed above; unknown columns end up as custom properties or are ignored.