Harmony

AI-Powered Farcaster Mini App for healthier social media conversations

Overview

  • I architected and deployed Harmony, a production-grade Farcaster Mini App designed to foster healthier social media conversations.
  • The system analyzes user casts in real-time for hate speech and bias using a sophisticated, cost-optimized AI pipeline.
  • It features a native Farcaster bot (`@harmony`), a "Happy Friday" leaderboard for positive community members, and a full web interface for deep text analysis (coming soon).

System Architecture

1. Unified Cloudflare Deployment
  • Frontend Client: Next.js 15 (App Router) deployed to Cloudflare Workers using OpenNext. This enables server-side rendering (SSR) and static generation directly at the edge, ensuring global low latency.
  • Backend Intelligence: Cloudflare Workers (Serverless V8 Isolate) acting as the API Gateway. It handles webhook events, REST endpoints, and orchestrates the AI analysis pipeline.
  • Infrastructure: The entire stack leverages Cloudflare’s ecosystem, including KV for caching, R2 for storage, and Durable Objects for distributed rate limiting.
2. AI Analysis Pipeline
  • Primary Logic: A multi-stage classifier (Waterfall pattern).
  • Models: Google Gemini 1.5 Flash, HuggingFace Inference API, and local rule-based heuristics.

Key Decisions & Rationale

1. Unified Serverless Architecture (Full-Stack Cloudflare)

Context: Managing separate providers for frontend (e.g., Vercel) and backend (e.g., AWS/Cloudflare) adds latency and operational complexity.

Decision: I deployed both the Next.js frontend and the API backend to Cloudflare Workers.

Why:

  • Performance: Using opennextjs-cloudflare, the React frontend renders at the Edge, right alongside the backend logic, minimizing network hops.
  • Consistency: A single platform simplifies secrets management, deployment pipelines (wrangler), and observability.
  • Cost: Leveraging Cloudflare’s unified serverless pricing model reduced infrastructure overhead compared to splitting traffic across vendors.
2. Cost-Optimized “Waterfall” AI Pipeline

Context: Running a pure LLM (like GPT-4 or Gemini Pro) on every social media post is prohibitively expensive and slow.

Decision: I implemented a three-stage fallback mechanism:

  1. Stage 1 (Local): A zero-cost, rule-based PreFilter runs instantly on the Edge to catch obvious slurs or spam.
  2. Stage 2 (Specialized Model): If the text passes Stage 1, it’s sent to a lightweight HuggingFace classification model (DistilBERT-based) optimized for speed and low cost.
  3. Stage 3 (LLM Fallback): Only ambiguous or complex edge cases trigger the LLM models choosing what is available switching between Google Gemini API call or OpenAI API call.

Outcome: This reduced operational costs by ~90% compared to a “LLM-first” approach while maintaining high accuracy for nuanced harassment.

3. Protocol Abstraction via Neynar

Context: Building directly on raw Farcaster hubs requires significant infrastructure maintenance (managing Hubble instances).

Decision: I integrated Neynar as a middleware layer.

Why: It drastically simplified the read/write operations for the Farcaster protocol. Instead of managing hub sync state, I could focus on the application logic (Hate Speech detection) and rely on Neynar’s high-availability APIs for fetching casts and user profiles.

4. Background Processing for Community Engagement (Coming soon)

Context: Real-time analysis is reactive. I wanted a proactive feature to reward positive behavior.

Decision: I utilized Cron Triggers in Cloudflare Workers to implement the “Happy Friday” leaderboard.

Why: This decoupled heavy data processing (scanning 24h of trending casts) from the user-facing API. Every Friday at 1 PM ET, the worker automatically wakes up, processes the dataset, scores users based on sentiment, and publishes the results, creating a consistent engagement loop without manual intervention.

Outcome

A preliminary MVP was successfully deployed to production, handling real-time webhook events from Farcaster. The “Waterfall” AI pipeline proved effective in filtering toxicity while keeping costs manageable, and the serverless architecture has required zero maintenance since deployment. Further features like leaderboards and webhook @harmony is coming soon.