# m4nt/3cx-audio-recorder-extension architecture

> Architecture diagram of the GitHub repository m4nt/3cx-audio-recorder-extension, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/m4nt/3cx-audio-recorder-extension
- Repository: https://github.com/m4nt/3cx-audio-recorder-extension

## Overview

##### Project type and purpose
- This is a cross-browser extension (Chrome and Firefox) that integrates into the 3CX web chat UI to provide in-chat audio recording, preview, and sending functionality.
- Key indicators:
- Two top-level folders: `chrome-extension/` and `firefox-extension/`, each containing manifest, background, content scripts, and popup UI.
- README describes audio recording, custom player, and integration points.

##### File structure
- Top-level:
- LICENSE, README.md, an unused audio-3cx.zip, and two extension folders.
- Each extension folder contains:
- manifest.json – declares extension metadata, permissions, scripts, UI elements.
- background.js – persistent (or event-driven) background process for long-running tasks or central coordination.
- content.js – injected into the 3CX chat page; responsible for DOM injection (floating recorder UI, custom audio player) and direct interaction with page controls.
- No server or backend: all logic and storage run in the browser using WebExtension APIs and the Web Audio API.

##### README for additional insights
- Features: record, pause, resume, cancel, preview, send; custom audio player for sent/received messages; supports .webm, .ogg, .m4a.
- Dependencies: WebExtensions framework (common model for Chrome & Firefox).
- No remote backend—audio blobs are handled locally and injected into the chat form to be transmitted via 3CX.

##### Main components of the system (to include
a. Browser Host
- Chrome or Firefox
- Renders the 3CX chat web app
b. Extension Manifest
- Configures permissions (tabs, activeTab, storage, etc.), scripts, and UI entry points
c. Background Script
- Coordinates long-lived tasks
- Listens for messages from popup or content scripts
- May manage persistent storage or global state
d. Content Script
- Injected into 3CX chat page
- Creates floating recorder UI
- Hooks into chat input area to insert audio attachments
- Controls the Web Audio API for recording
- Communicates with background via message passing
e. Popup UI
- Sends commands to background or content
f. Web Audio & MediaRecorder APIs
- Underlying browser APIs for capturing and processing audio streams
g. 3CX Chat Page
- Web application that ultimately sends recorded audio to the server
h. Storage (optional)
- Local browser storage for temporary state (e.g., “pause” time, selected format)

##### Relationships and interactions
- User clicks “Record” button on the floating UI (content script) → Content script invokes MediaRecorder → Audio data chunks buffered locally.
- User “Pause/Resume/Cancel” → Content script controls MediaRecorder; interim state kept in memory or local storage.
- User clicks “Send” → Content script finalizes blob, presents preview UI, then injects the audio file into the 3CX chat input (via DOM manipulation or the chat’s JavaScript API).
- Content script ↔ Background script: use `browser.runtime.sendMessage` or `chrome.runtime.sendMessage` for any cross-script commands or to share state (e.g., user preferences set via popup).
- Popup UI ↔ Background: commands and state retrieval.
- All components coordinate through WebExtension messaging channels.

##### Architectural patterns and design principles
- Separation of concerns:
- UI (popup.html/js and injected recorder UI)
- Business logic & audio capture (content script)
- Background orchestration (background.js)
- Single code-base approach with slight tweaks per browser in manifest and permissions.
- Message bus pattern via extension messaging API.
- Leverage browser standard APIs (MediaRecorder, storage) to avoid custom backends.

- Browser Host (Chrome/Firefox)
- WebExtension Manifest
- Background Script
- Content Script + Injected Recorder UI
- Popup UI
- 3CX Chat Page
- MediaRecorder / Web Audio API
- User actions → Recorder UI → MediaRecorder
- MediaRecorder → Content Script → 3CX Chat Page
- Content Script ↔ Background Script (messaging)
- Popup UI ↔ Background Script
- UI elements (blue)
- Script logic (green)
- Browser pages / host (gray)
- Rectangles for components

## Diagram (Mermaid)

```mermaid
flowchart TD
    BrowserHost["Browser Host (Chrome/Firefox)"]:::host

    subgraph "Chrome Extension"
        MC["Manifest"]:::logic
        BC["Background Script"]:::logic
        CC["Content Script"]:::logic
        PC["Popup UI"]:::ui
    end

    subgraph "Firefox Extension"
        MF["Manifest"]:::logic
        BF["Background Script"]:::logic
        CF["Content Script"]:::logic
        PF["Popup UI"]:::ui
    end

    RecorderUI["Injected Recorder UI"]:::ui
    RecorderEngine["MediaRecorder / Web Audio API"]:::logic
    ChatPage["3CX Chat Page"]:::host
    Docs["Project Documentation"]:::host

    BrowserHost --> MC
    BrowserHost --> MF

    MC --> BC
    MC --> CC
    MC --> PC

    MF --> BF
    MF --> CF
    MF --> PF

    CC --> RecorderUI
    CF --> RecorderUI

    RecorderUI -->|"MediaRecorder.start()"| RecorderEngine
    RecorderEngine -->|"audio chunks"| CC
    RecorderEngine -->|"audio chunks"| CF

    CC -->|"inject audio blob"| ChatPage
    CF -->|"inject audio blob"| ChatPage

    CC <-->|"chrome.runtime.sendMessage"| BC
    CF <-->|"browser.runtime.sendMessage"| BF

    PC <-->|"chrome.runtime.sendMessage"| BC
    PF <-->|"browser.runtime.sendMessage"| BF

    BrowserHost --> ChatPage

    Docs

    click MC "https://github.com/m4nt/3cx-audio-recorder-extension/blob/main/chrome-extension/manifest.json"
    click MF "https://github.com/m4nt/3cx-audio-recorder-extension/blob/main/firefox-extension/manifest.json"
    click BC "https://github.com/m4nt/3cx-audio-recorder-extension/blob/main/chrome-extension/background.js"
    click BF "https://github.com/m4nt/3cx-audio-recorder-extension/blob/main/firefox-extension/background.js"
    click CC "https://github.com/m4nt/3cx-audio-recorder-extension/blob/main/chrome-extension/content.js"
    click CF "https://github.com/m4nt/3cx-audio-recorder-extension/blob/main/firefox-extension/content.js"
    click PC "https://github.com/m4nt/3cx-audio-recorder-extension/blob/main/chrome-extension/popup.html"
    click PC "https://github.com/m4nt/3cx-audio-recorder-extension/blob/main/chrome-extension/popup.js"
    click PF "https://github.com/m4nt/3cx-audio-recorder-extension/blob/main/firefox-extension/popup.html"
    click PF "https://github.com/m4nt/3cx-audio-recorder-extension/blob/main/firefox-extension/popup.js"
    click Docs "https://github.com/m4nt/3cx-audio-recorder-extension/blob/main/README.md"
    click Docs "https://github.com/m4nt/3cx-audio-recorder-extension/tree/main/LICENSE"

    classDef ui fill:#ACE7EF,stroke:#000
    classDef logic fill:#C8E6C9,stroke:#000
    classDef host fill:#E0E0E0,stroke:#000
```
