# jamesbrill/react-speech-recognition architecture

> Architecture diagram of the GitHub repository jamesbrill/react-speech-recognition, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jamesbrill/react-speech-recognition
- Repository: https://github.com/jamesbrill/react-speech-recognition

## Overview

##### Project type and purpose
- This is an open-source React library—specifically a hook and helper object—that plugs into a React app to expose microphone speech as a transcript and command callbacks.
- Not a full-stack app or microservice: it is a front-end-only utility that wraps the browser’s Web Speech API (and optional polyfills) for easy React integration.

##### File structure
- src/
– index.js: exports the hook (`useSpeechRecognition`) and the controller object (`SpeechRecognition`).
– RecognitionManager.js: central singleton managing recognition state and API calls.
– NativeSpeechRecognition.js: adapter for the browser’s built-in Web Speech API.
– actions.js & reducers.js: Redux-style action types and reducer logic for maintaining transcript, listening status, error flags, etc.
– constants.js & utils.js: shared enums and helper functions (e.g. normalizing commands, matching splats).
– isAndroid.js: platform detection for Android-specific tweaks.
– SpeechRecognition.js: high-level façade that exposes start/stop/abort functions and applies polyfills.
- docs/: design and usage docs, migration guide, API reference, polyfill instructions.
- package.json & biome.json: build, test, lint configuration.
- .github/workflows: CI pipelines for test coverage and publishing.
- tests/: unit and integration tests.

##### README for architectural insights
- Core runtime: React hook ↔ RecognitionManager ↔ Web Speech API or polyfill.
- Polyfill extension points: `SpeechRecognition.applyPolyfill()`.
- Global state: only one recognition “engine” shared across all hook invocations.
- Command matching subsystem: pattern-matching on interim/final results with fuzzy logic.

##### Main components
a. React Application Layer
– Your React components (e.g. Dictaphone)
– `useSpeechRecognition` hook instance
b. Library Core
– SpeechRecognition façade (startListening, stopListening, abortListening, applyPolyfill)
– RecognitionManager (singleton)
– State store powered by actions.js & reducers.js
– Command matcher & callback dispatcher
c. Speech Engine Adapter
– NativeSpeechRecognition (Web Speech API wrapper)
– [Optional] Polyfill adapter (e.g. Azure via createSpeechServicesPonyfill)
d. Underlying Services & Hardware
– Browser’s Web Speech API (Chrome/Safari/Edge)
– Microphone hardware (user media)
– External cloud (only when polyfill is present: Azure, Google, etc.)

##### Relationships and data flows
- User click → SpeechRecognition.startListening() → RecognitionManager invokes adapter.start() → browser microphone stream → Web Speech API / polyfill processes audio → emits interim/final results → NativeSpeechRecognition callbacks → RecognitionManager dispatches ACTIONS.RECEIVE_RESULT → reducer updates transcript state → `useSpeechRecognition` hook triggers React re-render → component displays transcript or runs command callbacks.
- SpeechRecognition.applyPolyfill() swaps out NativeSpeechRecognition with a Ponyfill adapter before any listening begins.
- Commands defined in the hook flow down to RecognitionManager → matcher in utils.js triggers user callbacks on match events.

##### Architectural patterns & design principles
- Singleton manager for cross-component global state.
- Redux-style pattern (actions + reducers) for predictable state transitions.
- Adapter pattern for speech recognition engines (native vs polyfill).
- Hook API for declarative integration into React’s render lifecycle.

##### Essential architectural elements
- Don’t just show `useSpeechRecognition` → “SpeechRecognition engine”; break out the RecognitionManager, adapter layer, state store, and command matcher.
- Polyfill extension point as a swap in the adapter layer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% React Application Layer
    subgraph "React Application Layer"
        Component["React Component (e.g. Dictaphone)"]:::react
        Hook["useSpeechRecognition Hook"]:::react
    end

    %% Library Core
    subgraph "Library Core"
        Facade["SpeechRecognition Facade"]:::core
        Manager["RecognitionManager Singleton"]:::core
        Store["State Store (actions.js & reducers.js)"]:::core
        Actions["Actions Definitions"]:::core
        Reducer["Reducer Logic"]:::core
        Matcher["Command Matcher"]:::core
        Utils["Utility Functions"]:::core
        Constants["Shared Enums & Constants"]:::core
        Android["Android Detection"]:::core
    end

    %% Adapter Layer
    subgraph "Adapter Layer"
        Native["NativeSpeechRecognition Adapter"]:::adapter
        Polyfill["Polyfill Adapter"]:::adapter
    end

    %% External Services & Hardware
    subgraph "External Services & Hardware"
        Microphone["Microphone Hardware"]:::external
        BrowserAPI["Browser Web Speech API"]:::external
        Cloud["External Cloud Services"]:::external
    end

    %% Data Flows and Relationships
    Component -->|"uses"| Hook
    Hook -->|"calls startListening() etc."| Facade
    Facade -->|"invokes"| Manager
    Facade -->|"applyPolyfill()"| Polyfill
    Manager -->|"start()/stop()"| Native
    Manager -->|"start()/stop()"| Polyfill
    Native -->|"speech results"| Manager
    Polyfill -->|"speech results"| Manager
    Manager -->|"dispatches"| Actions
    Actions -->|"processed by"| Reducer
    Reducer -->|"updates"| Store
    Store -->|"state updates"| Hook
    Manager -->|"matches commands using"| Matcher
    Matcher -->|"uses"| Utils
    Manager -->|"uses config"| Constants
    Manager -->|"platform tweaks"| Android
    Store -->|"triggers re-render"| Hook
    Hook -->|"renders transcript"| Component
    Microphone -->|"audio stream"| Native
    BrowserAPI -->|"speech engine"| Native
    Cloud -->|"speech processing"| Polyfill

    %% Click Events
    click Hook "https://github.com/jamesbrill/react-speech-recognition/blob/master/src/index.js"
    click Facade "https://github.com/jamesbrill/react-speech-recognition/blob/master/src/SpeechRecognition.js"
    click Manager "https://github.com/jamesbrill/react-speech-recognition/blob/master/src/RecognitionManager.js"
    click Native "https://github.com/jamesbrill/react-speech-recognition/blob/master/src/NativeSpeechRecognition.js"
    click Actions "https://github.com/jamesbrill/react-speech-recognition/blob/master/src/actions.js"
    click Reducer "https://github.com/jamesbrill/react-speech-recognition/blob/master/src/reducers.js"
    click Utils "https://github.com/jamesbrill/react-speech-recognition/blob/master/src/utils.js"
    click Constants "https://github.com/jamesbrill/react-speech-recognition/blob/master/src/constants.js"
    click Android "https://github.com/jamesbrill/react-speech-recognition/blob/master/src/isAndroid.js"
    click Store "https://github.com/jamesbrill/react-speech-recognition/blob/master/src/actions.js"
    click Store "https://github.com/jamesbrill/react-speech-recognition/blob/master/src/reducers.js"
    click Tests "https://github.com/jamesbrill/react-speech-recognition/tree/master/tests/"
    click Docs "https://github.com/jamesbrill/react-speech-recognition/tree/master/docs/"

    %% Styles
    classDef react fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef core fill:#D0FFD0,stroke:#333,stroke-width:1px
    classDef adapter fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
```
