Knowledge Wiki Orchestrata Ultimate

Orchestrata Ultimate / Specs / 018-fireflies-integration

018-fireflies-integration: Fireflies Integration

The Fireflies Integration is a VizInt Command Center gadget that brings meeting intelligence from Fireflies.ai into the Orchestrata dashboard. It displays recent meeting transcripts, enables keyword search across all meetings, shows AI-generated meeting summaries, and links meeting notes to orchestrata sessions and iterations. The gadget connects to the Fireflies API via REST calls from the browser and optionally through a Python-side MCP bridge for server-side API access.

At a glance

Item Value
Spec directory specs/018-fireflies-integration/
Status line in the spec Draft
Requirement IDs defined 80
With a @traces citation in src/ 12 (15.0%)
With a @traces citation in tests/ 0 (0.0%)
Tracked files 6
RTM page 018-fireflies-integration

Reading this spec

The Fireflies Integration is a VizInt Command Center gadget that brings content from the Fireflies.ai service into the Orchestrata dashboard, so that it can be read, searched and linked to orchestration work without leaving the Command Center. The spec's aim is traceability: material from the service is linked to specific sessions and iterations.

The scope is six user stories: listing recent items, searching by keyword, displaying summaries, linking items to sessions and iterations, configuring the connection, and a server-side bridge for access when the browser is restricted. The functional groups are listing, keyword search, summaries, session linking and bridge integration. Requirement IDs use the REQ-018- prefix.

The design is a browser-side JavaScript gadget calling the Fireflies REST API, with an optional Python-side MCP bridge (FirefliesMCPBridge) for server-side access when browser CORS is restrictive. Session and iteration links are stored locally and optionally synchronized to the gateway through State Sync. The gadget registers with the Command Center through a GadgetManifest in the productivity category.

In the code, the Python side is in orchestrata_ultimate/session/fireflies_tools, orchestrata_ultimate/integrations/fireflies_client and orchestrata_ultimate/gateway/handlers/fireflies. The per-requirement view is on the RTM page.

The spec's status line reads Draft. It tracks 6 files and defines 80 requirement IDs. The full text follows below.

Measured coverage is 12 of 80 requirements cited by at least one @traces in src/ (15.0%), spread over 3 modules; the module citing the most of them is orchestrata_ultimate/session/fireflies_tools (10 requirements). In tests/, 0 requirements are cited by a test-side @traces.

Coverage gaps: 68 requirements have no citing symbol. The largest untraced groups are REQ-018-* (68). Untraced means no @traces names the ID; the behaviour may still exist in code that was never annotated. Test-side citations are thinner than code-side ones (0 against 12).

Requirements

Checkbox is the state recorded in the requirements checklist; Traced by is the count of src/ symbols whose @traces names the ID.

ID Done Requirement Traced by
REQ-018-001 no Gadget displays a scrollable list of recent meetings none
REQ-018-002 no Each entry shows: title, date, duration, participant count none
REQ-018-003 no List sorted by date descending (most recent first) none
REQ-018-004 no Pagination loads 20 transcripts per page none
REQ-018-005 no Infinite scroll triggers next page load at bottom none
REQ-018-006 no Clicking a meeting entry expands to show the full transcript none
REQ-018-007 no Transcript text formatted with speaker labels and timestamps none
REQ-018-008 no Long transcripts (> 100,000 chars) lazy-loaded in chunks none
REQ-018-009 no Speaker segments visually differentiated by color none
REQ-018-010 no Collapsing a transcript preserves scroll position in list none
REQ-018-011 no Last sync timestamp displayed in gadget header none
REQ-018-012 no Manual refresh button re-fetches transcript list 1
REQ-018-013 no Auto-refresh every 10 minutes (configurable) none
REQ-018-014 no Cached transcripts served when API is unavailable none
REQ-018-015 no Loading skeleton shown during initial fetch none
REQ-018-016 no Search input field in gadget header none
REQ-018-017 no Search debounced at 300ms (configurable) none
REQ-018-018 no Search results replace transcript list view none
REQ-018-019 no Empty search returns to recent meetings list none
REQ-018-020 no Each result shows: meeting title, date, matching excerpt none
REQ-018-021 no Keywords highlighted in excerpts with <mark> elements none
REQ-018-022 no Excerpt shows 100 characters before and after the match none
REQ-018-023 no Results ranked by relevance (match count) none
REQ-018-024 no Results paginated (20 per page) none
REQ-018-025 no Multi-word queries supported none
REQ-018-026 no Last 10 search queries stored in localStorage none
REQ-018-027 no Search history accessible via dropdown on focus none
REQ-018-028 no Clicking a history entry re-executes the search none
REQ-018-029 no Search history clearable from settings none
REQ-018-030 no Total result count displayed in header none
REQ-018-031 no Each meeting has "Transcript" and "Summary" tabs none
REQ-018-032 no Summary tab shows: key topics, action items, decisions, follow-ups none
REQ-018-033 no Each summary section is collapsible none
REQ-018-034 no Action items displayed as a checklist (read-only) none
REQ-018-035 no Decisions displayed as a bullet list none
REQ-018-036 no Summary fetched on first tab switch (not on list load) none
REQ-018-037 no Loading skeleton shown while fetching none
REQ-018-038 no Fetched summaries cached for session duration none
REQ-018-039 no "Summary not available" displayed for unprocessed meetings none
REQ-018-040 no Manual refresh button re-fetches summary none
REQ-018-041 no "Link to Session" button on each meeting entry none
REQ-018-042 no Session selector shows recent sessions from session.list RPC none
REQ-018-043 no Each session option shows: number, purpose, date none
REQ-018-044 no Optional iteration number selector within session none
REQ-018-045 no Meeting linkable to multiple sessions none
REQ-018-046 no Linked sessions shown as tags on meeting entry none
REQ-018-047 no Tag includes session number and purpose excerpt none
REQ-018-048 no Clicking tag navigates to session in session-manager gadget none
REQ-018-049 no Remove link via tag context menu (x button) none
REQ-018-050 no Linked meeting count visible in session-manager gadget detail view none
REQ-018-051 no Links stored in localStorage under commandcenter.state.fireflies.session_links none
REQ-018-052 no Links synced to gateway via State Sync none
REQ-018-053 no fireflies.meeting.linked event emitted on ctx.bus none
REQ-018-054 no fireflies.meeting.unlinked event emitted on removal none
REQ-018-055 no Duplicate links prevented (idempotent) none
REQ-018-056 no Settings panel with API key input field none
REQ-018-057 no API key encrypted with AES-GCM via Web Crypto API none
REQ-018-058 no "Test Connection" button validates API key 2
REQ-018-059 no Connection status indicator: green/yellow/red none
REQ-018-060 no Clear instructions for obtaining Fireflies API key none
REQ-018-061 no Toggle between browser-direct and MCP bridge mode none
REQ-018-062 no MCP bridge URL input visible when bridge mode selected none
REQ-018-063 no Browser-direct mode is default none
REQ-018-064 no Mode change triggers reconnection test none
REQ-018-065 no Settings persisted in localStorage none
REQ-018-066 no fireflies.transcripts RPC method returns transcript list 5
REQ-018-067 no fireflies.transcript RPC method returns single transcript with full text 5
REQ-018-068 no fireflies.search RPC method returns search results 5
REQ-018-069 no fireflies.summary RPC method returns meeting summary 5
REQ-018-070 no All methods require read_only gateway scope minimum 1
REQ-018-071 no MCP bridge implemented as SPEC-015 plugin none
REQ-018-072 no Plugin uses existing Fireflies MCP tools 1
REQ-018-073 no Plugin authenticates with server-side Fireflies API key 4
REQ-018-074 no Plugin caches responses for 10 minutes (configurable) 2
REQ-018-075 no Plugin respects Fireflies API rate limits 1
REQ-018-076 no If MCP bridge unreachable, gadget falls back to browser-direct mode none
REQ-018-077 no Fallback requires local API key to be configured none
REQ-018-078 no User notified of fallback via connection status indicator none
REQ-018-079 no Bridge reconnection attempted periodically (every 60s) none
REQ-018-080 no Bridge health checked via gateway RPC 2

Code that traces this spec

Module Symbols Requirements
orchestrata_ultimate/gateway/handlers/fireflies 7 7
orchestrata_ultimate/integrations/fireflies_client 7 7
orchestrata_ultimate/session/fireflies_tools 8 10

Checklists

checklists/README.md

Fireflies Integration Checklists

Project: Orchestrata Fireflies Integration (Spec 018) Component: Fireflies Gadget + MCP Bridge Status: Planning Phase Owner: Architecture Team

Overview

The Fireflies Integration is a VizInt Command Center gadget that brings meeting intelligence from Fireflies.ai into the Orchestrata dashboard. It displays meeting transcripts, enables keyword search, shows AI-generated summaries, and links meeting notes to orchestrata sessions and iterations. The gadget supports browser-direct API access and an optional Python-side MCP bridge for server-side API access.

Checklist Summary
Checklist Total Items Completed Progress
Requirements 80+ 0 0%
Constitutional Compliance 55+ 0 0%
Testing Plan 130+ 0 0%
TOTAL 265+ 0 0%
Key Responsibilities
1. Transcript Display
3. Meeting Summaries
4. Session Linking
5. MCP Bridge (Optional)
Performance Targets
Metric Target Critical Threshold
Transcript List Fetch < 2s P95 < 4s P99
Search Query < 3s P95 < 5s P99
Summary Fetch < 2s P95 < 4s P99
Transcript Render (50K chars) < 200ms < 500ms
Cache Hit < 10ms < 50ms
MCP Bridge Round-Trip < 4s P95 < 6s P99
Memory Usage (20 transcripts) < 15MB < 25MB
Checklist Files
1. requirements.md

Functional requirements organized by user stories:

2. constitutional.md

Compliance with all 11 constitutional articles covering agent autonomy, Prolog governance, session isolation, extensibility, testing standards, observability, graceful degradation, and versioning.

3. testing.md

Comprehensive testing strategy:

Integration Points
Upstream Dependencies
Downstream Consumers
Dependencies
Required APIs
Required Libraries
Optional Services
References

Last Updated: 2026-03-28 Version: 1.0.0 Maintained By: Architecture Team

checklists/constitutional.md

Fireflies Integration - Constitutional Compliance

Component: Fireflies Gadget Spec: 018-fireflies-integration Status: Compliance Review Total Compliance Items: 55+

Overview

This document tracks compliance of the Fireflies Integration gadget with the Orchestrata Constitution. As a browser-side productivity gadget with an optional Python MCP bridge, the Fireflies integration must meet security, observability, and extensibility requirements while maintaining data privacy for meeting transcripts.

Article I: Agent Autonomy

Principle: Agents retain autonomy; gadgets observe and assist without interference.

Compliance Requirements

Priority: Medium Verification: Code review + integration tests

Article II: Prolog as Single Source of Truth

Principle: Governance rules defined in Prolog.

Compliance Requirements

Priority: Medium Verification: Integration tests

Article III: Session Isolation

Principle: Sessions are isolated; state does not leak between sessions.

Compliance Requirements

Priority: High Verification: Integration tests

Article IV: Hooks for Extensibility

Principle: Extension points for customization without core modification.

Compliance Requirements

Priority: Medium Verification: Architecture review

Article V: Minimal Core, Maximal Extension

Principle: Core is minimal; features added via extensions.

Compliance Requirements

Priority: High Verification: Architecture review

Article VI: Implementation Standards

Principle: JavaScript ES2024 (browser) and Python 3.14t (bridge).

Compliance Requirements

Priority: High Verification: Code review + linting

Article VII: Testing Without Mocks

Principle: Tests use real implementations.

Compliance Requirements

Priority: Critical Verification: Test code review

Article VIII: Metrics and Observability

Principle: All operations observable and measurable.

Compliance Requirements

Priority: Medium Verification: Log review + observability tests

Article IX: Graceful Degradation

Principle: System degrades gracefully under failure.

Compliance Requirements

Priority: High Verification: Failure injection tests

Article X: Version Compatibility

Principle: APIs are versioned; breaking changes avoided.

Compliance Requirements

Priority: Medium Verification: Compatibility tests

Article XI: Documentation First

Principle: Documentation precedes implementation.

Compliance Requirements

Priority: High Verification: Documentation review

Summary Statistics
Article Total Items Completed Percentage
Article I (Autonomy) 5 0 0%
Article II (Prolog) 5 0 0%
Article III (Isolation) 5 0 0%
Article IV (Hooks) 5 0 0%
Article V (Minimal Core) 5 0 0%
Article VI (Implementation) 5 0 0%
Article VII (No Mocks) 5 0 0%
Article VIII (Observability) 5 0 0%
Article IX (Degradation) 5 0 0%
Article X (Versioning) 5 0 0%
Article XI (Documentation) 5 0 0%
TOTAL 55 0 0%

Last Updated: 2026-03-28 Version: 1.0.0 Maintained By: Architecture Team

checklists/requirements.md

The requirement list above comes from this file; 0 of 80 checkbox items are ticked.

checklists/testing.md

Fireflies Integration - Testing Plan

Component: Fireflies Gadget Spec: 018-fireflies-integration Status: Test Planning Phase Total Test Cases: 130+

Overview

This document defines the testing strategy for the Fireflies Integration gadget. All tests follow the strict "no mocking" policy. Unit tests use JSDOM for real DOM interaction, integration tests use real Fireflies API (test account), and E2E tests use Playwright with a real browser.

Test Categories Summary
Category Test Count Purpose Priority
Unit Tests 55+ Core logic validation Critical
Integration Tests 35+ API and system integration Critical
E2E Tests 25+ Full browser workflow High
Performance Tests 15+ Latency and rendering High
TOTAL 130+
Unit Tests (55+)
Transcript List (10 tests)
Search Panel (10 tests)
Summary Panel (10 tests)
Session Linker (10 tests)
API Provider (10 tests)
Credential Management (5 tests)
Integration Tests (35+)
Fireflies REST API (10 tests)
MCP Bridge Integration (10 tests)
Session Linking Integration (10 tests)
Credential Integration (5 tests)
E2E Tests (25+)
Performance Tests (15+)
Summary Statistics
Category Test Count Completed Percentage
Unit Tests 55 0 0%
Integration Tests 35 0 0%
E2E Tests 25 0 0%
Performance Tests 15 0 0%
TOTAL 130 0 0%

Last Updated: 2026-03-28 Version: 1.0.0 Maintained By: Architecture Team

Other tracked files

Full spec text

Verbatim from specs/018-fireflies-integration/spec.md; headings are pushed down two levels.

SPEC-018: Fireflies Integration

Metadata

Overview

What

The Fireflies Integration is a VizInt Command Center gadget that brings meeting intelligence from Fireflies.ai into the Orchestrata dashboard. It displays recent meeting transcripts, enables keyword search across all meetings, shows AI-generated meeting summaries, and links meeting notes to orchestrata sessions and iterations. The gadget connects to the Fireflies API via REST calls from the browser and optionally through a Python-side MCP bridge for server-side API access.

Why
How

User Scenarios & Stories

US-001: View Recent Meeting Transcripts

As a developer using the Command Center I want to see my recent meeting transcripts in a list So that I can quickly reference what was discussed without leaving the dashboard

Priority: P0

Acceptance Criteria:

US-002: Search Across Meetings

As a developer I want to search across all meeting transcripts by keyword So that I can find specific discussions about technical topics

Priority: P0

Acceptance Criteria:

US-003: Display Meeting Summaries

As a developer I want to see AI-generated meeting summaries So that I can quickly understand meeting outcomes without reading full transcripts

Priority: P1

Acceptance Criteria:

As a developer I want to link meeting notes to orchestrata sessions and iterations So that I have complete traceability between meetings and development work

Priority: P1

Acceptance Criteria:

US-005: Configure Fireflies Connection

As a developer I want to configure my Fireflies API connection So that the gadget can access my meeting data

Priority: P0

Acceptance Criteria:

US-006: MCP Bridge for Server-Side Access

As a system administrator I want a Python-side MCP bridge for Fireflies API access So that the gadget can work in environments where browser-side API calls are restricted by CORS

Priority: P2

Acceptance Criteria:

Standardized Acceptance Criteria

SAC-US001: View Recent Meeting Transcripts
# Criterion Verification
SAC-US001-01 Gadget displays a list of recent meetings with title, date, duration, and participant count DOM query for .fireflies-meeting-entry elements with child .title, .date, .duration, .participants
SAC-US001-02 List is sorted by date descending (most recent first) Assert data-date attribute of each entry is monotonically decreasing
SAC-US001-03 Each meeting entry is expandable to show the full transcript Click .meeting-entry → assert .transcript-content visibility toggles
SAC-US001-04 Transcript text is formatted with speaker labels and timestamps Assert expanded transcript contains .speaker-label and .timestamp elements
SAC-US001-05 Pagination loads additional meetings (20 per page) Scroll to bottom → assert new API call with offset=20 → assert additional entries appended
SAC-US001-06 Last sync timestamp displayed in the gadget header Assert .sync-timestamp element displays ISO 8601 formatted time
SAC-US001-07 Manual refresh button re-fetches the transcript list Click .refresh-btn → assert API call fired → assert list updated
SAC-US002: Search Across Meetings
# Criterion Verification
SAC-US002-01 Search input field in the gadget header with real-time search (debounced 300ms) Type in .search-input → assert API call fires after 300ms debounce, not before
SAC-US002-02 Search results show matching meetings with highlighted keyword context Assert .search-result entries contain <mark> elements wrapping the matched keyword
SAC-US002-03 Each result includes meeting title, date, and the matching transcript excerpt Assert .search-result contains .title, .date, .excerpt child elements
SAC-US002-04 Results are ranked by relevance (most keyword matches first) Assert data-match-count attribute of results is monotonically decreasing
SAC-US002-05 Cleared search returns to the recent meetings list view Clear .search-input → assert transcript list view is restored
SAC-US002-06 Search supports multi-word queries Search "gateway authentication" → assert results returned for multi-word phrase
SAC-US002-07 Search history (last 10 queries) stored in localStorage for quick re-search After 10 searches → assert localStorage.getItem('commandcenter.state.fireflies.search_history') contains 10 entries
SAC-US003: Display Meeting Summaries
# Criterion Verification
SAC-US003-01 Each meeting entry includes a "Summary" tab alongside the "Transcript" tab Assert .tab-summary and .tab-transcript elements present per meeting entry
SAC-US003-02 Summary displays: key topics, action items, decisions made, and follow-ups Assert .summary-topics, .summary-actions, .summary-decisions, .summary-followups sections populated
SAC-US003-03 Summary sections are collapsible for space efficiency Click section header → assert content visibility toggles via aria-expanded attribute
SAC-US003-04 Action items are displayed as a checklist (read-only, reflecting Fireflies data) Assert .action-item elements have type="checkbox" with disabled attribute and correct checked state
SAC-US003-05 Summary loading shows a skeleton loader while fetching Assert .skeleton-loader visible during API call → hidden after response
SAC-US003-06 If no summary is available, the tab displays "Summary not yet generated" API returns no summary data → assert .no-summary-message with text "Summary not yet generated"
# Criterion Verification
SAC-US004-01 Each meeting entry has a "Link to Session" button that opens a session selector Assert .link-session-btn present → click → assert .session-selector dialog visible
SAC-US004-02 Session selector shows recent sessions with number, purpose, and date Assert .session-option entries contain .session-number, .session-purpose, .session-date
SAC-US004-03 A meeting can be linked to one or more sessions Link meeting to session A and session B → assert both links persisted in localStorage
SAC-US004-04 A meeting can be linked to specific iterations within a session Select session → select iteration → assert link data includes iteration_number field
SAC-US004-05 Linked sessions are displayed as tags on the meeting entry After linking → assert .session-tag elements visible on the meeting entry
SAC-US004-06 The session-manager gadget shows linked meetings via ctx.bus Emit fireflies.meeting.linked → assert session-manager gadget updates its display
SAC-US004-07 Meeting-session links stored in localStorage and synced via State Sync Assert localStorage.getItem('commandcenter.state.fireflies.session_links') contains link → assert State Sync push called
SAC-US004-08 Removing a link is possible via the meeting entry context menu Right-click meeting → select "Remove Link" → assert link removed from storage and tags
SAC-US005: Configure Fireflies Connection
# Criterion Verification
SAC-US005-01 Settings panel provides an API key input field Assert .api-key-input element of type password present in settings panel
SAC-US005-02 API key is stored in localStorage encrypted with Web Crypto API (AES-GCM) After saving key → assert stored value is base64-encoded ciphertext, not plaintext
SAC-US005-03 "Test Connection" button verifies the API key by fetching a single transcript Click .test-connection-btn → assert API call to transcripts endpoint with limit=1
SAC-US005-04 Connection status indicator shows green/yellow/red After successful test → assert .status-indicator has data-status="connected" with green styling
SAC-US005-05 Option to choose browser-direct API access or MCP bridge mode Assert .mode-selector radio group with browser_direct and mcp_bridge options
SAC-US005-06 MCP bridge URL configurable when bridge mode is selected Select mcp_bridge → assert .bridge-url-input becomes visible and editable
SAC-US005-07 Clear instructions on how to obtain a Fireflies API key Assert .setup-instructions element contains text referencing Fireflies developer portal
SAC-US006: MCP Bridge for Server-Side Access
# Criterion Verification
SAC-US006-01 Python MCP bridge exposes Fireflies API methods as gateway-accessible RPC calls Send fireflies.transcripts RPC → assert valid response with transcript array
SAC-US006-02 Bridge uses the existing Fireflies MCP tools Assert bridge implementation delegates to fireflies_get_transcript, fireflies_search, fireflies_get_summary, fireflies_get_transcripts
SAC-US006-03 Bridge authenticates with Fireflies using server-side API key Assert API key not included in browser-bound RPC responses; assert server-side config contains key
SAC-US006-04 Gateway RPC methods registered under fireflies.* namespace Assert gateway method registry contains fireflies.transcripts, fireflies.search, fireflies.summary, fireflies.transcript
SAC-US006-05 Bridge caches transcript data for 10 minutes Fetch transcript → fetch again within 10 min → assert no upstream API call on second fetch
SAC-US006-06 Bridge respects Fireflies API rate limits Send 100 rapid requests → assert bridge queues or throttles to stay within rate limit

Functional Requirements

FR-001: Transcript Listing

User Story: US-001

User Story: US-002

FR-003: Meeting Summaries

User Story: US-003

FR-004: Session Linking

User Story: US-004

FR-005: MCP Bridge Integration

User Story: US-006

Non-Functional Requirements

Performance

NFR-001: Data Fetching

NFR-002: Rendering

Reliability

NFR-003: Offline Behavior

NFR-004: Data Integrity

Security

NFR-005: Credential Management

NFR-006: Data Privacy

Technical Design

Architecture
┌──────────────────────────────────────────────────────┐
│            Fireflies Gadget (Browser)                  │
├──────────────────────────────────────────────────────┤
��                                                        │
│  ┌──────────────┐  ┌──────────────┐ ┌────────────┐   │
│  │ Transcript   │  │  Search      │ │  Summary   │   │
│  │ List View    │  │  Panel       │ │  Panel     │   │
│  └──────────────┘  └──────────────┘ └──���─────────┘   │
│         │                 │               │            │
│         ▼                 ▼               ▼            │
│  ┌──────────────┐  ┌──────────────┐                   │
│  │  Session     │  │  Transcript  │                   │
│  │  Linker      │  │  Cache       │                   │
│  └──���───────────┘  └──────────────┘                   │
│         │                 │                            │
│         ▼                 ▼                            │
│  ┌────────────────────────────────────────────┐       │
│  │           Fireflies API Provider            │       │
│  │  ┌──────────────┐  ┌──────────────┐        │       │
│  │  │ Browser-     │  │ MCP Bridge   │        │       │
│  │  ��� Direct Mode  │  │ Mode         │        │       │
│  │  │ (REST API)   │  │ (via GW RPC) │        │       │
│  │  └──────────────┘  ��──────────────┘        │       │
│  └──────────────────────────────────��─────────┘       │
│         │                 │                            │
│         ▼                 ▼                            │
│  ┌──────────────┐  ┌──────────────┐                   │
│  │  ctx.bus      │  │ localStorage │                   │
│  │ (session      │  │ (API key,    │                   │
│  │  links)       │  │  links,      │                   │
│  │               │  │  cache)      │                   │
│  └──────────────┘  └──────────────┘                   │
└──────────────────────────────────────────────────────┘
          │                           │
          ▼                           ▼
┌──────────────────┐    ┌──────────────────────┐
│  Fireflies.ai    │    │  SPEC-014 Gateway    │
│  REST API        │    │  (MCP Bridge mode)   │
│  (api.fireflies  │    │  fireflies.* RPC     │
│   .ai/graphql)   │    │  methods             │
└──────────────────┘    └──────────────────────┘
Key Interfaces
/**
 * FirefliesGadget — Main gadget class for Fireflies.ai integration.
 */
class FirefliesGadget {
    /** Mount the gadget into the Command Center grid. */
    async mount(ctx) {}

    /** Unmount and clean up subscriptions and cache. */
    async unmount() {}

    /** Refresh transcript list from API. */
    async refresh() {}

    /** Search across all transcripts. */
    async search(query) {}
}

/**
 * IFirefliesProvider — Protocol for Fireflies API access.
 */
class IFirefliesProvider {
    /** Fetch list of recent transcripts. */
    async getTranscripts(limit, offset) {}

    /** Fetch a single transcript by ID. */
    async getTranscript(transcriptId) {}

    /** Search transcripts by keyword. */
    async search(query, limit, offset) {}

    /** Fetch AI-generated summary for a transcript. */
    async getSummary(transcriptId) {}

    /** Test the API connection. */
    async testConnection() {}

    /** Get provider status. */
    getStatus() {}
}

/**
 * FirefliesBrowserProvider — Browser-direct Fireflies API access.
 */
class FirefliesBrowserProvider extends IFirefliesProvider {
    constructor(apiKey) {}
}

/**
 * FirefliesMCPProvider — MCP bridge Fireflies API access via gateway RPC.
 */
class FirefliesMCPProvider extends IFirefliesProvider {
    constructor(gadgetBridge) {}
}

/**
 * SessionLinker — Manages meeting-to-session/iteration links.
 */
class SessionLinker {
    /** Link a meeting to a session. */
    async linkToSession(meetingId, sessionId, iterationNumber) {}

    /** Remove a meeting-session link. */
    async unlinkFromSession(meetingId, sessionId) {}

    /** Get all sessions linked to a meeting. */
    getLinkedSessions(meetingId) {}

    /** Get all meetings linked to a session. */
    getLinkedMeetings(sessionId) {}
}
Gadget Manifest
{
    "id": "orchestrata-fireflies",
    "name": "Fireflies Meetings",
    "version": "1.0.0",
    "description": "Meeting transcripts, search, and summaries from Fireflies.ai",
    "entry": "gadgets/fireflies/fireflies.js",
    "icon": "microphone",
    "category": "productivity",
    "dependencies": ["GadgetBridge"],
    "min_api_version": "1.0.0",
    "default_size": {"columns": 2, "rows": 2},
    "supports_multi_instance": false,
    "config_schema": {
        "type": "object",
        "properties": {
            "mode": {
                "type": "string",
                "enum": ["browser_direct", "mcp_bridge"],
                "default": "browser_direct"
            },
            "mcp_bridge_url": {"type": "string"},
            "transcripts_per_page": {"type": "integer", "default": 20},
            "cache_ttl_minutes": {"type": "integer", "default": 10},
            "search_debounce_ms": {"type": "integer", "default": 300}
        }
    }
}

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title": "MeetingSessionLink",
    "type": "object",
    "required": ["meeting_id", "meeting_title", "session_id"],
    "properties": {
        "meeting_id": {"type": "string"},
        "meeting_title": {"type": "string"},
        "meeting_date": {"type": "string", "format": "date-time"},
        "session_id": {"type": "string"},
        "session_number": {"type": "integer"},
        "iteration_number": {
            "type": ["integer", "null"],
            "description": "Optional specific iteration within the session."
        },
        "linked_at": {"type": "string", "format": "date-time"},
        "linked_by": {"type": "string", "default": "user"}
    }
}
MCP Bridge RPC Methods (via SPEC-014 Gateway)

When operating in MCP bridge mode, the following RPC methods are available:

{
    "fireflies.transcripts": {
        "params": {"limit": 20, "offset": 0},
        "result": {"transcripts": [...], "count": 20}
    },
    "fireflies.transcript": {
        "params": {"transcript_id": "abc123"},
        "result": {"id": "abc123", "title": "...", "text": "...", "speakers": [...]}
    },
    "fireflies.search": {
        "params": {"query": "gateway authentication", "limit": 20},
        "result": {"results": [...], "count": 5}
    },
    "fireflies.summary": {
        "params": {"transcript_id": "abc123"},
        "result": {"topics": [...], "action_items": [...], "questions": [...]}
    }
}
Configuration
# In configs/command-center.yaml under gadgets section
gadgets:
  orchestrata-fireflies:
    mode: "browser_direct"
    transcripts_per_page: 20
    cache_ttl_minutes: 10
    search_debounce_ms: 300

# If using MCP bridge mode (in configs/monolithic.yaml)
plugins:
  orchestrata-plugin-fireflies-bridge:
    api_key: «redacted»
    cache_ttl_seconds: 600
    rate_limit_rpm: 60
Integration Points
Component Integration
SPEC-016 VizInt Command Center Gadget lifecycle, chrome, ctx.bus, GadgetBridge, StateSync
Fireflies.ai REST API Transcript listing, search, summary retrieval
Fireflies MCP tools Server-side API access via MCP bridge
SPEC-014 WebSocket Gateway MCP bridge RPC methods (fireflies.* namespace)
SPEC-015 Plugin SDK MCP bridge plugin registration
ctx.bus Meeting-session link events, session lifecycle awareness
localStorage API key storage, session links, search history, cache

Success Criteria

  1. Transcript Display: Recent meeting transcripts displayed within 3 seconds of gadget mount
  2. Search: Keyword search returns relevant results within 3 seconds with highlighted excerpts
  3. Summaries: AI-generated meeting summaries displayed with structured sections (topics, actions, decisions)
  4. Session Linking: Meetings linkable to sessions/iterations with bidirectional visibility
  5. Dual Mode: Both browser-direct and MCP bridge modes operational
  6. Offline Resilience: Cached transcripts and summaries visible when API is unreachable

Visual Architecture

Class Diagram

Diagram source shown as text: Mermaid could not parse it (Error: Parse error on line 36:).

classDiagram-direction LR
    class CheetahClawsTUI {
        +__init__()
        #_load_commands(): dict[str, Any]
        +async create_checkpoint(name: str): dict[str, Any]
        +async rewind(steps: int = 1): dict[str, Any]
        +async query_memory(query: str, depth: int = 1): dict[str, Any]
        +async edit_file(file_path: str, old_string: str, new_string: str): dict[str, Any]
        +async search_files(pattern: str, path: str = '.'): list[str]
        +async execute_command(command: str, args: list[str] | None = None): dict[str, Any]
    }
    class OpenRouterProvider {
        +__init__(api_key: str | None = None)
        +async chat_completion(model: str, messages: list[dict[str, str]], **kwargs): dict[str, Any]
        +get_available_models(): list[str]
        +get_model_cost(model: str): float
    }
    class TodoistIntegration {
        +__init__(api_key: str | None = None)
        +is_configured(): bool
        +async create_project(name: str): str
        +async create_task(project_id: str, title: str, **kwargs): str
        +async sync_tasks(project_id: str): list[dict[str, Any]]
        +async close()
    }
    class VizIntWebUI {
        +__init__(host: str = 'localhost', port: int = 8765)
        +async start()
        +async shutdown()
        +async add_project(project_data: dict[str, Any])
        +async broadcast_edit_complete(file_path: str, result: dict[str, Any])
        +async update_task_status(task_id: str, status: str)
        +async get_projects(): list[dict[str, Any]]
    }
FirefliesTranscript Schema
{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title": "FirefliesTranscript",
    "type": "object",
    "required": ["id", "title", "date", "duration_minutes"],
    "properties": {
        "id": {"type": "string"},
        "title": {"type": "string"},
        "date": {"type": "string", "format": "date-time"},
        "duration_minutes": {"type": "number"},
        "participant_count": {"type": "integer"},
        "participants": {
            "type": "array",
            "items": {"type": "string"}
        },
        "text": {
            "type": "string",
            "description": "Full transcript text. May be null in list views (fetched on demand)."
        },
        "speakers": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "segments": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "start_time": {"type": "number"},
                                "end_time": {"type": "number"},
                                "text": {"type": "string"}
                            }
                        }
                    }
                }
            }
        }
    }
}
FirefliesSummary Schema
{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title": "FirefliesSummary",
    "type": "object",
    "required": ["transcript_id"],
    "properties": {
        "transcript_id": {"type": "string"},
        "topics": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "title": {"type": "string"},
                    "summary": {"type": "string"}
                }
            }
        },
        "action_items": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "text": {"type": "string"},
                    "assignee": {"type": "string"},
                    "completed": {"type": "boolean"}
                }
            }
        },
        "questions": {
            "type": "array",
            "items": {"type": "string"}
        },
        "follow_ups": {
            "type": "array",
            "items": {"type": "string"}
        }
    }
}
FirefliesSearchResult Schema
{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title": "FirefliesSearchResult",
    "type": "object",
    "required": ["transcript_id", "title", "date", "excerpt"],
    "properties": {
        "transcript_id": {"type": "string"},
        "title": {"type": "string"},
        "date": {"type": "string", "format": "date-time"},
        "excerpt": {
            "type": "string",
            "description": "Contextual excerpt with keyword match (100 chars before and after)."
        },
        "match_count": {"type": "integer"},
        "relevance_score": {"type": "number"}
    }
}

Error Conditions and Edge Cases

Governance

GOV-001: Ownership and Maintenance

Component Owner: Mohamed Technical Lead: Mohamed Maintenance Responsibility: Orchestrata Core Team

The Fireflies Integration specification is owned and maintained by the Orchestrata Core Team. All changes to the specification MUST be reviewed and approved by the technical lead before implementation.

GOV-002: Change Management

Change Approval Process:

  1. Change proposal submitted via pull request
  2. Technical review by component owner
  3. Security review (if applicable)
  4. Performance impact assessment
  5. Backward compatibility verification
  6. Merge upon approval

Breaking Changes:

GOV-003: Compliance and Standards

API Compliance:

Data Governance:

Security Governance:

GOV-004: Deprecation Policy

Deprecation Triggers:

Deprecation Process:

  1. Minimum 90-day notice period
  2. Migration guide published
  3. Alternative solutions documented
  4. Support continues during notice period
  5. Final removal with major version increment
GOV-005: Support and SLA

Response Times:

Compatibility Guarantee:

Performance Requirements

Testability Considerations

Definition of Done

Examples

Example: Fetching Recent Transcripts (Browser-Direct)
const response = await fetch('https://api.fireflies.ai/graphql', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`,
    },
    body: JSON.stringify({
        query: `
            query {
                transcripts(limit: 20, skip: 0) {
                    id
                    title
                    date
                    duration
                    participants
                }
            }
        `,
    }),
});
const { data } = await response.json();
// data.transcripts = [{id, title, date, duration, participants}, ...]

const searchResponse = await fetch('https://api.fireflies.ai/graphql', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`,
    },
    body: JSON.stringify({
        query: `
            query SearchTranscripts($keyword: String!) {
                transcripts(search: $keyword, limit: 20) {
                    id
                    title
                    date
                    sentences {
                        text
                        speaker_name
                    }
                }
            }
        `,
        variables: { keyword: 'gateway authentication' },
    }),
});

{
    "meeting_id": "ff-transcript-abc123",
    "meeting_title": "Architecture Review - WebSocket Gateway",
    "meeting_date": "2026-03-27T14:00:00Z",
    "session_id": "session-089",
    "session_number": 89,
    "iteration_number": 202,
    "linked_at": "2026-03-28T10:30:00Z",
    "linked_by": "user"
}
Example: MCP Bridge RPC Call
{
    "jsonrpc": "2.0",
    "id": "cc-req-042",
    "method": "fireflies.search",
    "params": {
        "query": "plugin sandboxing",
        "limit": 20
    }
}

Response:

{
    "jsonrpc": "2.0",
    "id": "cc-req-042",
    "result": {
        "results": [
            {
                "transcript_id": "ff-abc123",
                "title": "Architecture Review - Plugin System",
                "date": "2026-03-25T10:00:00Z",
                "excerpt": "...discussed **plugin sandboxing** using Linux namespaces and cgroups...",
                "match_count": 3,
                "relevance_score": 0.87
            }
        ],
        "count": 1
    }
}
Example: Summary Display
{
    "transcript_id": "ff-abc123",
    "topics": [
        {
            "title": "Plugin Sandboxing Approach",
            "summary": "Team decided to use Linux namespaces for filesystem isolation and cgroups for resource limiting."
        },
        {
            "title": "Capability System",
            "summary": "Plugins must declare capabilities in manifest. DI container scoped by declared capabilities."
        }
    ],
    "action_items": [
        {
            "text": "Write SPEC-015 Plugin SDK specification",
            "assignee": "Mohamed",
            "completed": true
        },
        {
            "text": "Prototype capability enforcement in DI container",
            "assignee": "Mohamed",
            "completed": false
        }
    ],
    "questions": [
        "Should plugin manifests use YAML format (plugin.yaml)?",
        "Can reserved aliases (U:Ox, U:PS, U:KR) be overridden by plugins?"
    ],
    "follow_ups": [
        "Review OpenClaw plugin architecture for additional patterns",
        "Benchmark plugin hot-reload performance"
    ]
}

Contracts

Contract: Fireflies Gadget API (contracts/commandcenter/fireflies-v1.0.0.yaml)
info:
  title: Fireflies Integration Gadget Contract
  version: 1.0.0
  spec_id: 018-fireflies-integration
  spec_version: 1.0.0
  maturity: experimental
  consumer: fireflies-gadget
  providers: [fireflies-rest-api, fireflies-mcp-bridge]

schemas:
  FirefliesTranscript:
    type: object
    required: [id, title, date, duration_minutes]
    properties:
      id:
        type: string
      title:
        type: string
      date:
        type: string
        format: date-time
      duration_minutes:
        type: number
      participant_count:
        type: integer
      participants:
        type: array
        items:
          type: string
      text:
        type: string
        nullable: true

  FirefliesSummary:
    type: object
    required: [transcript_id]
    properties:
      transcript_id:
        type: string
      topics:
        type: array
        items:
          type: object
          properties:
            title:
              type: string
            summary:
              type: string
      action_items:
        type: array
        items:
          type: object
          properties:
            text:
              type: string
            assignee:
              type: string
            completed:
              type: boolean
      questions:
        type: array
        items:
          type: string
      follow_ups:
        type: array
        items:
          type: string

  FirefliesSearchResult:
    type: object
    required: [transcript_id, title, date, excerpt]
    properties:
      transcript_id:
        type: string
      title:
        type: string
      date:
        type: string
        format: date-time
      excerpt:
        type: string
      match_count:
        type: integer
      relevance_score:
        type: number

  MeetingSessionLink:
    type: object
    required: [meeting_id, meeting_title, session_id]
    properties:
      meeting_id:
        type: string
      meeting_title:
        type: string
      meeting_date:
        type: string
        format: date-time
      session_id:
        type: string
      session_number:
        type: integer
      iteration_number:
        type: integer
        nullable: true
      linked_at:
        type: string
        format: date-time
      linked_by:
        type: string

mcp_bridge_methods:
  fireflies.transcripts:
    description: Fetch list of recent transcripts
    scope_required: read_only
    params:
      type: object
      properties:
        limit:
          type: integer
          default: 20
        offset:
          type: integer
          default: 0
    result:
      type: object
      required: [transcripts, count]
      properties:
        transcripts:
          type: array
          items:
            $ref: "#/schemas/FirefliesTranscript"
        count:
          type: integer
          description: >
            Number of items in THIS page. The Fireflies GraphQL API exposes
            no corpus-wide total; a field named "total" here would lie
            (2026-07-12 defect fix — page size was being reported as total).

  fireflies.transcript:
    description: Fetch a single transcript with full text
    scope_required: read_only
    params:
      type: object
      required: [transcript_id]
      properties:
        transcript_id:
          type: string
    result:
      $ref: "#/schemas/FirefliesTranscript"

  fireflies.search:
    description: Search across transcripts by keyword
    scope_required: read_only
    params:
      type: object
      required: [query]
      properties:
        query:
          type: string
        limit:
          type: integer
          default: 20
        offset:
          type: integer
          default: 0
    result:
      type: object
      required: [results, count]
      properties:
        results:
          type: array
          items:
            $ref: "#/schemas/FirefliesSearchResult"
        count:
          type: integer
          description: Number of results in this page (no corpus total upstream).

  fireflies.summary:
    description: Fetch AI-generated meeting summary
    scope_required: read_only
    params:
      type: object
      required: [transcript_id]
      properties:
        transcript_id:
          type: string
    result:
      $ref: "#/schemas/FirefliesSummary"

bus_events:
  fireflies.meeting.linked:
    description: Emitted when a meeting is linked to a session/iteration
    payload:
      $ref: "#/schemas/MeetingSessionLink"
  fireflies.meeting.unlinked:
    description: Emitted when a meeting-session link is removed
    payload:
      type: object
      required: [meeting_id, session_id]
      properties:
        meeting_id:
          type: string
        session_id:
          type: string

performance:
  transcript_list_p95_ms: 2000
  search_p95_ms: 3000
  summary_p95_ms: 2000
  transcript_render_p95_ms: 200
  cache_hit_ms: 10
  mcp_roundtrip_p95_ms: 4000

security:
  api_key_storage: localStorage_aes_gcm
  transcript_persistence: ephemeral_memory_only
  link_data_persistence: localStorage_and_state_sync
  api_transport: https_only

spec_traceability:
  spec_id: "018-fireflies-integration"
  spec_version: "1.0.0"
  user_stories: ["US-001", "US-002", "US-003", "US-004", "US-005", "US-006"]

Observability Requirements

OBS-001: Structured Logging

All Fireflies gadget and MCP bridge operations SHALL emit structured log entries.

Browser-Side Logging (Gadget)

Event Level Fields Destination
Transcript list fetched INFO timestamp, transcript_count, fetch_duration_ms, mode (browser/bridge) console.log (structured JSON)
Transcript expanded INFO timestamp, transcript_id, text_length, render_duration_ms console.log
Search query submitted INFO timestamp, query, result_count, search_duration_ms console.log
Summary fetched INFO timestamp, transcript_id, has_topics, has_actions, fetch_duration_ms console.log
Meeting linked to session INFO timestamp, meeting_id, session_id, iteration_number console.log
API key validation INFO timestamp, status (success/failure), mode console.log
API call failed ERROR timestamp, endpoint, status_code, error_message, retry_after_ms console.error
Cache hit DEBUG timestamp, cache_key, cache_age_ms console.debug
Cache miss DEBUG timestamp, cache_key, reason (expired/absent) console.debug
Fallback to browser-direct WARNING timestamp, bridge_url, error_message console.warn

Server-Side Logging (MCP Bridge)

Event Level Fields Destination
RPC method invoked INFO timestamp, method, params, correlation_id, client_id Gateway structured log
Fireflies API call INFO timestamp, endpoint, duration_ms, status_code, correlation_id Gateway structured log
Fireflies API error ERROR timestamp, endpoint, status_code, error_body, correlation_id Gateway structured log
Rate limit hit WARNING timestamp, endpoint, retry_after_s, correlation_id Gateway structured log
Cache hit (bridge) DEBUG timestamp, cache_key, cache_age_s, correlation_id Gateway structured log
Bridge plugin loaded INFO timestamp, plugin_id, version, configured_mode Gateway structured log
Bridge plugin error ERROR timestamp, plugin_id, error_type, error_message, stack_trace Gateway structured log
OBS-002: Metrics

Browser-Side Metrics (Gadget)

Metrics are collected in-memory and exposed via ctx.bus event fireflies.metrics.snapshot for dashboard display.

Metric Type Labels Description
fireflies_api_calls_total Counter endpoint, mode, status Total API calls to Fireflies
fireflies_api_duration_ms Histogram endpoint, mode API call duration in milliseconds
fireflies_cache_hits_total Counter cache_type (transcript/summary/search) Total cache hits
fireflies_cache_misses_total Counter cache_type Total cache misses
fireflies_search_queries_total Counter result_bucket (0, 1-5, 6-20, 20+) Total search queries by result count bucket
fireflies_transcript_renders_total Counter size_bucket (small/medium/large) Transcript render events by text size
fireflies_session_links_total Gauge — Current number of meeting-session links
fireflies_errors_total Counter error_type (auth/network/rate_limit/parse) Total errors by type

Server-Side Metrics (MCP Bridge)

Metrics are exposed via the gateway's Prometheus endpoint.

Metric Type Labels Description
fireflies_bridge_rpc_total Counter method, status Total RPC calls handled by the bridge
fireflies_bridge_rpc_duration_seconds Histogram method RPC call duration including upstream API time
fireflies_bridge_upstream_calls_total Counter endpoint, status_code Total calls to Fireflies upstream API
fireflies_bridge_upstream_duration_seconds Histogram endpoint Upstream API call duration
fireflies_bridge_cache_size_bytes Gauge — Current size of the bridge transcript cache
fireflies_bridge_cache_entries Gauge cache_type Number of cached entries by type
fireflies_bridge_rate_limit_throttles_total Counter endpoint Times the bridge throttled due to rate limits
OBS-003: Distributed Tracing
Span Name Parent Attributes
fireflies.rpc.{method} Gateway request span rpc.method, client_id, correlation_id
fireflies.upstream.{endpoint} fireflies.rpc.{method} http.url, http.method, http.status_code, duration_ms
fireflies.cache.lookup fireflies.rpc.{method} cache.hit, cache.key, cache.age_ms
OBS-004: Health Checks

Browser-Side Health (Gadget)

The gadget SHALL expose its health status via ctx.bus event fireflies.health and display it in the gadget chrome status indicator.

{
    "status": "healthy",
    "components": {
        "api_connection": {
            "status": "healthy",
            "mode": "browser_direct",
            "last_successful_call": "2026-03-28T14:30:00Z",
            "latency_ms": 850
        },
        "cache": {
            "status": "healthy",
            "entries": 20,
            "oldest_entry_age_ms": 540000
        },
        "local_storage": {
            "status": "healthy",
            "links_count": 5,
            "api_key_configured": true
        }
    },
    "uptime_ms": 3600000
}

Health status mapping:

Server-Side Health (MCP Bridge)

The MCP bridge plugin SHALL report health via the gateway's plugin health system.

{
    "status": "healthy",
    "components": {
        "fireflies_api": {
            "status": "healthy",
            "last_successful_call": "2026-03-28T14:30:00Z",
            "latency_ms": 420
        },
        "cache": {
            "status": "healthy",
            "entries": 45,
            "size_bytes": 2340000,
            "hit_rate_percent": 73.2
        },
        "rate_limiter": {
            "status": "healthy",
            "remaining_calls": 42,
            "reset_at": "2026-03-28T14:31:00Z"
        }
    },
    "uptime_seconds": 86400
}

Health check polling interval: 60 seconds (configurable via health_check_interval_s in plugin config).

API Contracts

REST API Endpoints
# Example endpoint definition
GET /api/v1/resource/{id}
Response (200):
  type: object
  required:
    - id
    - name
  properties:
    id: { type: string }
    name: { type: string }
Response (404):
  $ref: '#/components/schemas/ErrorResponse'
Error Response Schema
components:
  schemas:
    ErrorResponse:
      type: object
      required:
        - error
        - message
        - timestamp
      properties:
        error: { type: string }
        message: { type: string }
        timestamp: { type: string, format: date-time }
        request_id: { type: string }
        trace_id: { type: string }
        details: { type: array, items: { type: object } }
API Versioning

All APIs use path-based versioning (/api/v1/). Breaking changes require increment to v2.

Revision History

Date Version Author Changes
2026-03-28 1.0.0 Mohamed Initial specification