Skip to content

implementation.md

Latest commit

 

History

History
100 lines (61 loc) · 4.71 KB

implementation.md

File metadata and controls

100 lines (61 loc) · 4.71 KB

Marketing Moment Analyzer

Real-time X/Twitter analysis tool. Tells you if now is a good time to post about something.

Why This Tool?

Assignment was vague: "add a marketing tool." Could've built anything - content calendar, competitor tracker, SEO analyzer, posting scheduler. Went with timing intelligence instead.

Marketers already know what to post. The hard part is when. Is this a good moment? Is the conversation hot? Are competitors dominating? Any PR landmines out there?

Real-time social signals can answer that. Felt more useful than another dashboard.

The Process

Didn't jump straight into code. Used AI (Claude code in plan mode) to write a full spec first - that's the requirements.md file (398 lines). Defined everything upfront: what signals to track, how to weight them, what thresholds to use, API structure, error handling.

Planning took ~30 min but saved me from debugging in circles later. Had a blueprint, just executed it. Way faster than coding blind and refactoring three times.

How It Works

Ask the bot "Is it a good time to launch my coffee shop in Seattle?" and it fires 4 queries to X/Twitter simultaneously:

  • Trends (last 6 hours): Is this topic hot right now? Post volume, influencers talking about it, hashtags trending
  • Sentiment (last 3 hours): What's the public mood? Excited? Angry? Neutral? Ratio of positive to negative posts
  • Competition (last 12 hours): Are competitors making noise? Launches, campaigns, share of voice
  • Risks (last 24 hours): Any PR disasters brewing? Controversies, regulatory news, backlash

Each query returns signals like TRENDING_HIGH or SENTIMENT_NEGATIVE or COMPETITOR_SILENT. Signals get weights - trending surge is +20, PR crisis is -20, warm sentiment is +10, etc. Sum them up, you get a score 0-100.

  • 70+: GREEN - Post now, good moment
  • 40-69: YELLOW - Monitor, mixed signals
  • 0-39: RED - Hold off, risky moment

Takes ~16 seconds. You see progress bars for each dimension as it analyzes.

Design Decisions

Parallel queries instead of sequential. 4 API calls at once takes 16 seconds. One by one would be 48 seconds. Waiting sucks.

Weighted signals. Not all signals matter equally. A trending surge (+20) beats a minor risk (-6). Reflected that in the scoring.

Graceful degradation. If one query times out, the other three still work. Partial data beats no data. Each dimension fails independently.

Streaming progress UI. You watch it analyze trends, then sentiment, then competition, then risks. Feels interactive instead of just waiting. More honest too - you see the tool thinking.

No historical comparison. Would've been cool to say "score is up 15pts from yesterday" but didn't have time. Focused on current moment analysis instead.

The Constraints

Had 2-3 hours total. Made cuts:

  • No caching (fresh query every time - simple but slow)
  • No tests (prioritized working code)
  • No historical tracking (just current state)
  • English only (Grok limitation)
  • No retry logic (fail fast, move on)

Shipped substance over polish. Working live data beats a polished mock.

If I Had More Time

Cool stuff I'd add:

  • Historical view: "Score jumped 15pts in the last hour - something's brewing"
  • Multi-competitor tracking: Compare 3-5 brands at once, see who's loud
  • Multi-platform signals: Add Reddit, LinkedIn, TikTok - not just X
  • Alert system: "Ping me when coffee shop score crosses 70"
  • Caching: Don't re-query if you asked 2 minutes ago

What I Learned

Planning first actually saves time. Feels counterintuitive - you want to start coding. But spending 30 min on requirements.md meant I didn't rewrite the scoring algorithm three times. Clear spec → clean implementation.

AI works way better with specs. Give Claude "build a marketing tool" and you get spaghetti. Give it a 398-line requirements doc and it builds exactly what you asked for. Garbage in, garbage out.

Real-time data is harder but more valuable. Could've mocked everything - return fake GREEN signals, ship in an hour. But a fake timing signal is useless. Real X/Twitter analysis based on what's happening right now? That's a product.

Running It

XAI_API_KEY=xai-... pnpm dev

Go to localhost:3000, ask: "Is it a good time to post about [topic]?"

Watch it query X, analyze signals, spit out a score.

Files

lib/ai/tools/marketing-moment-analyzer.ts  # 390 lines - core logic
components/marketing-progress.tsx          # streaming UI
components/marketing-moment-result.tsx     # result card
hooks/use-marketing-progress.tsx           # state
+ mods to: types, prompts, message rendering, data stream handler

Full technical spec in requirements.md if you want signal weights, API formats, thresholds, etc.