--- name: fireflies-reference-architecture description: 'Design meeting intelligence architecture with Fireflies.ai GraphQL API, webhooks, and CRM sync. Use when designing new integrations, planning transcript pipelines, or establishing architecture for meeting analytics platforms. Trigger with phrases like "fireflies architecture", "fireflies design", "fireflies project structure", "meeting intelligence pipeline". ' allowed-tools: Read, Grep version: 1.11.0 license: MIT author: Jeremy Longshore tags: - saas - fireflies - architecture compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw --- # Fireflies.ai Reference Architecture ## Overview Production architecture for meeting intelligence using Fireflies.ai. Event-driven pipeline: meetings are recorded by the Fireflies bot, transcripts arrive via webhook, then are processed for action items, analytics, and CRM sync. ## Architecture ``` ┌──────────────────────────────────────────────────────┐ │ Meeting Sources │ │ Zoom │ Google Meet │ MS Teams │ Upload API │ └──────────┬───────────────────────────────┬───────────┘ │ Bot auto-joins │ uploadAudio ▼ ▼ ┌──────────────────────────────────────────────────────┐ │ Fireflies.ai Platform │ │ Transcription → Speaker ID → AI Summary → Actions │ └───────────────────────┬──────────────────────────────┘ │ Webhook: "Transcription completed" │ Payload: { meetingId, eventType } ▼ ┌──────────────────────────────────────────────────────┐ │ Your Webhook Receiver │ │ 1. Verify x-hub-signature (HMAC-SHA256) │ │ 2. ACK 200 immediately │ │ 3. Queue for async processing │ └───────────────────────┬──────────────────────────────┘ │ ┌────────────┼────────────┐ ▼ ▼ ▼ ┌──────────────┐ ┌────────┐ ┌──────────────┐ │ Transcript │ │ Action │ │ Analytics │ │ Storage │ │ Items │ │ Engine │ │ (DB/Search) │ │ (CRM) │ │ (Dashboards) │ └──────────────┘ └────────┘ └──────────────┘ ``` ## Core Components ### 1. GraphQL Client Layer ```typescript // lib/fireflies.ts const FIREFLIES_API = "https://api.fireflies.ai/graphql"; export async function firefliesQuery(query: string, variables?: any) { const res = await fetch(FIREFLIES_API, { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${process.env.FIREFLIES_API_KEY}`, }, body: JSON.stringify({ query, variables }), }); const json = await res.json(); if (json.errors) throw new Error(json.errors[0].message); return json.data; } ``` ### 2. Webhook Processor ```typescript // services/webhook-processor.ts import crypto from "crypto"; interface TranscriptEvent { meetingId: string; eventType: string; clientReferenceId?: string; } export async function processWebhookEvent(event: TranscriptEvent) { // Fetch full transcript const { transcript } = await firefliesQuery(` query($id: String!) { transcript(id: $id) { id title date duration organizer_email speakers { id name } sentences { speaker_name text start_time end_time ai_filters { task question sentiment } } summary { overview action_items keywords topics_discussed } meeting_attendees { displayName email } analytics { sentiments { positive_pct negative_pct neutral_pct } speakers { name duration word_count questions words_per_minute } } } } `, { id: event.meetingId }); // Process in parallel await Promise.all([ storeTranscript(transcript), syncActionItems(transcript), updateAnalytics(transcript), ]); return transcript; } ``` ### 3. Transcript Storage ```typescript // services/transcript-store.ts interface StoredMeeting { firefliesId: string; title: string; date: string; duration: number; speakers: string[]; overview: string; actionItems: string[]; keywords: string[]; sentiment: { positive: number; negative: number; neutral: number }; } async function storeTranscript(transcript: any): Promise { const meeting: StoredMeeting = { firefliesId: transcript.id, title: transcript.title, date: transcript.date, duration: transcript.duration, speakers: transcript.speakers.map((s: any) => s.name), overview: transcript.summary?.overview || "", actionItems: transcript.summary?.action_items || [], keywords: transcript.summary?.keywords || [], sentiment: { positive: transcript.analytics?.sentiments?.positive_pct || 0, negative: transcript.analytics?.sentiments?.negative_pct || 0, neutral: transcript.analytics?.sentiments?.neutral_pct || 0, }, }; // Store in your database await db.meetings.upsert({ where: { firefliesId: meeting.firefliesId }, data: meeting }); return meeting; } ``` ### 4. Action Item Sync ```typescript // services/action-items.ts async function syncActionItems(transcript: any) { const items = transcript.summary?.action_items || []; if (items.length === 0) return; const attendees = transcript.meeting_attendees?.map((a: any) => a.email) || []; for (const item of items) { await taskManager.create({ title: item.slice(0, 200), source: `Fireflies: ${transcript.title}`, meetingId: transcript.id, meetingDate: transcript.date, participants: attendees, }); } console.log(`Synced ${items.length} action items from "${transcript.title}"`); } ``` ### 5. Meeting Analytics ```typescript // services/analytics.ts async function buildWeeklyReport() { const since = new Date(Date.now() - 7 * 86400000).toISOString(); const data = await firefliesQuery(` query($fromDate: DateTime) { transcripts(fromDate: $fromDate, limit: 100) { id title date duration participants summary { action_items keywords } analytics { speakers { name duration word_count } sentiments { positive_pct } } } } `, { fromDate: since }); const meetings = data.transcripts; return { totalMeetings: meetings.length, totalHours: (meetings.reduce((s: number, m: any) => s + m.duration, 0) / 60).toFixed(1), actionItems: meetings.reduce((s: number, m: any) => s + (m.summary?.action_items?.length || 0), 0), topKeywords: aggregateKeywords(meetings).slice(0, 10), avgSentiment: avgSentiment(meetings), }; } function aggregateKeywords(meetings: any[]): [string, number][] { const counts: Record = {}; for (const m of meetings) { for (const kw of m.summary?.keywords || []) { counts[kw] = (counts[kw] || 0) + 1; } } return Object.entries(counts).sort((a, b) => b[1] - a[1]); } ``` ### 6. Audio Upload Pipeline ```typescript // services/upload.ts async function uploadRecording(fileUrl: string, title: string, attendees?: any[]) { return firefliesQuery(` mutation($input: AudioUploadInput) { uploadAudio(input: $input) { success title message } } `, { input: { url: fileUrl, title, attendees: attendees?.map(a => ({ displayName: a.name, email: a.email })), webhook: process.env.WEBHOOK_URL, client_reference_id: `upload-${Date.now()}`, }, }); } ``` ## Project Layout ``` meeting-intelligence/ src/ lib/fireflies.ts # GraphQL client services/ webhook-processor.ts # Event handler transcript-store.ts # DB persistence action-items.ts # CRM/task sync analytics.ts # Aggregation upload.ts # Audio upload api/ webhooks/fireflies.ts # Webhook endpoint health.ts # Health check types/fireflies.ts # TypeScript interfaces tests/ fixtures/ # Recorded API responses services/ # Service unit tests ``` ## Error Handling | Issue | Cause | Solution | |-------|-------|----------| | Missing transcript | `meetingId` invalid | Log and skip, alert on repeated failures | | Empty summary | Meeting too short | Check duration > 1 min before processing | | Duplicate webhook | Network retry | Use `meetingId` as idempotency key | | Rate limit on batch | Many transcripts at once | Queue with PQueue (1 req/sec) | ## Output - Event-driven architecture with webhook-triggered processing - Transcript storage with search-ready schema - Action item extraction and CRM sync pipeline - Meeting analytics aggregation engine ## Resources - [Fireflies API Docs](https://docs.fireflies.ai/) - [Fireflies Webhooks](https://docs.fireflies.ai/graphql-api/webhooks) - [Transcript Query](https://docs.fireflies.ai/graphql-api/query/transcript) ## Next Steps For multi-environment deployment, see `fireflies-multi-env-setup`.