fireflies-reference-architecture（萤火虫参考架构）

Fireflies.ai Reference Architecture

Overview

Production architecture for meeting intelligence with Fireflies.ai. Covers transcript processing pipelines, CRM integration, action item extraction, and meeting analytics dashboards using the GraphQL API.

Prerequisites

• Fireflies.ai API key with GraphQL access
• GraphQL client (graphql-request or urql)
• CRM system for action item sync (optional)
• Database for transcript storage

Architecture Diagram

┌──────────────────────────────────────────────────────┐
│              Meeting Sources                          │
│  Zoom │ Google Meet │ Teams │ Dialpad │ Phone        │
└──────────┬───────────────────────────────┬───────────┘
           │                               │
           ▼                               ▼
┌──────────────────────┐     ┌─────────────────────────┐
│  Fireflies.ai Bot    │     │  Upload API             │
│  (auto-join meetings)│     │  (manual recordings)    │
└──────────┬───────────┘     └──────────┬──────────────┘
           │                            │
           ▼                            ▼
┌──────────────────────────────────────────────────────┐
│              Fireflies Processing                     │
│  Transcription │ Speaker ID │ AI Summary │ Actions   │
└──────────────────────────┬───────────────────────────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
     ┌──────────────┐ ┌────────┐ ┌──────────────┐
     │ Transcript   │ │ Action │ │ Webhook      │
     │ Storage      │ │ Items  │ │ Events       │
     │ (DB/Search)  │ │ (CRM)  │ │ (Real-time)  │
     └──────────────┘ └────────┘ └──────────────┘

Instructions

Step 1: GraphQL Client Setup

import { GraphQLClient } from 'graphql-request';

const fireflies = new GraphQLClient('https://api.fireflies.ai/graphql', {
  headers: { Authorization: `Bearer ${process.env.FIREFLIES_API_KEY}` },
});

// Fetch recent transcripts
const GET_TRANSCRIPTS = `
  query GetTranscripts($limit: Int) {
    transcripts(limit: $limit) {
      id title date duration
      organizer_email participants
      summary { overview action_items keywords }
    }
  }
`;

async function getRecentMeetings(limit = 20) {
  const data = await fireflies.request(GET_TRANSCRIPTS, { limit });
  return data.transcripts;
}

Step 2: Transcript Processing Pipeline

const GET_FULL_TRANSCRIPT = `
  query GetTranscript($id: String!) {
    transcript(id: $id) {
      id title
      sentences {
        speaker_name text
        start_time end_time
      }
      summary { overview action_items keywords }
      meeting_attendees { displayName email }
    }
  }
`;

interface ProcessedMeeting {
  id: string;
  title: string;
  attendees: string[];
  actionItems: string[];
  keyTopics: string[];
  speakerBreakdown: Record<string, number>;
}

async function processMeeting(id: string): Promise<ProcessedMeeting> {
  const { transcript } = await fireflies.request(GET_FULL_TRANSCRIPT, { id });

  const speakerTime: Record<string, number> = {};
  for (const s of transcript.sentences) {
    const duration = s.end_time - s.start_time;
    speakerTime[s.speaker_name] = (speakerTime[s.speaker_name] || 0) + duration;
  }

  return {
    id: transcript.id,
    title: transcript.title,
    attendees: transcript.meeting_attendees.map((a: any) => a.email),
    actionItems: transcript.summary.action_items || [],
    keyTopics: transcript.summary.keywords || [],
    speakerBreakdown: speakerTime,
  };
}

Step 3: Webhook Integration

import express from 'express';
const app = express();

app.post('/webhooks/fireflies', express.json(), async (req, res) => {
  const { event_type, meeting_id, transcript_id } = req.body;

  if (event_type === 'Transcription completed') {
    const meeting = await processMeeting(transcript_id);

    // Sync action items to CRM
    for (const item of meeting.actionItems) {
      await createCRMTask(item, meeting.attendees);
    }
  }

  res.json({ received: true });
});

Step 4: Meeting Analytics Aggregation

async function weeklyMeetingReport() {
  const meetings = await getRecentMeetings(50);
  const oneWeekAgo = Date.now() - 7 * 86400000;  # 86400000 = configured value

  const recent = meetings.filter(
    (m: any) => new Date(m.date).getTime() > oneWeekAgo
  );

  return {
    totalMeetings: recent.length,
    totalHours: recent.reduce((s: number, m: any) => s + m.duration / 3600, 0).toFixed(1),  # 3600: timeout: 1 hour
    topAttendees: countAttendees(recent).slice(0, 5),
    actionItemCount: recent.reduce((s: number, m: any) =>
      s + (m.summary?.action_items?.length || 0), 0),
  };
}

Error Handling

Examples

Quick Meeting Search

async function searchMeetings(keyword: string) {
  const meetings = await getRecentMeetings(100);
  return meetings.filter((m: any) =>
    m.title?.toLowerCase().includes(keyword.toLowerCase()) ||
    m.summary?.keywords?.some((k: string) => k.toLowerCase().includes(keyword))
  );
}

Resources

• Fireflies GraphQL API
• Fireflies Webhooks
• Fireflies Integrations

Output

• Configuration files or code changes applied to the project
• Validation report confirming correct implementation
• Summary of changes made and their rationale