# nicksheaharty/bedsidekick-app architecture

> Architecture diagram of the GitHub repository nicksheaharty/bedsidekick-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nicksheaharty/bedsidekick-app
- Repository: https://github.com/nicksheaharty/bedsidekick-app

## Overview

##### Project type and purpose
- BedSidekick is an embedded Node.js–based IoT application running on a Raspberry Pi.
- It’s primarily a hardware-software system providing real-time conversational AI, voice I/O, and visual feedback on an LCD.

##### File structure
- Top level:
- .env / package.json / README.md – environment/config
- public/index.html – optional web interface or status page
- src/ – TypeScript/JavaScript source
- src/services/ – AudioService, ElevenLabsService (TTS), GeminiService (AI chat)
- dist/ – transpiled output mirroring src for deployment on the Pi
- No database directory, no web-framework folder (so this is not a classic full-stack web app but an embedded service)
- Hardware interfaces (LCD, microphone, speaker) are accessed via service modules, possibly using native Python bindings or Node packages

##### README for additional insights
- External systems:
- Google Gemini API for conversation
- ElevenLabs API for voice synthesis
- Hardware:
- USB microphone → Audio input
- Speaker → Audio output
- I2C LCD → Display
- Core features:
- AI conversation loop
- Mood/emotion monitoring
- Alerting caregivers (future or via API)
- HIPAA-compliant data handling (local encryption)

##### Main components & their interactions
a. Hardware layer (on the Raspberry Pi):
– Microphone (audio in)
– Speaker (audio out)
– LCD display (I2C)
b. Application layer (Node.js processes):
– AudioService
- Captures raw audio from mic
- Sends for speech-to-text (if implemented) or handles audio buffering
– GeminiService
- Sends text to Google Gemini
- Receives AI response (text + emotion metadata)
– ElevenLabsService
- Takes AI text + voice ID
- Calls ElevenLabs API to synthesize speech audio
– LCDService
– Controller / Orchestrator (index.js)
- Coordinates the audio → AI → TTS → play-back loop
- Monitors mood scores, triggers alerts if thresholds exceeded
c. External services (cloud):
– Google Gemini API (chat + emotion inference)
– ElevenLabs API (TTS)

##### Architectural patterns & design principles
- Modular service-oriented layers: each external integration encapsulated in its own service module
- Single process, event-driven orchestration (Node.js)
- Hardware abstraction: treat mic, speaker, LCD as pluggable modules
- Separation of concerns: AI logic vs TTS vs display vs I/O

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Hardware Layer"
        MIC["Microphone"]:::hardware
        SPK["Speaker"]:::hardware
        LCD_HW["LCD Display"]:::hardware
    end

    subgraph "Application (Node.js Runtime)"
        CONFIG_ENV[".env"]:::config
        CONFIG_PKG["package.json"]:::config
        ORCH["Orchestrator / Controller"]:::internal
        AUDIO["AudioService"]:::internal
        GEM["GeminiService"]:::internal
        ELE["ElevenLabsService"]:::internal
        LCD["LCDService"]:::internal
        ALERT["Alert Module"]:::internal
        WEB["Web Interface (Status Page)"]:::frontend
        DOC["README.md"]:::doc
    end

    subgraph "Cloud Services"
        GEM_API["Google Gemini API"]:::external
        ELE_API["ElevenLabs API"]:::external
        CARE["Caregiver Notification"]:::external
    end

    MIC -->|"audio stream"| AUDIO
    AUDIO -->|"text request"| GEM
    GEM -->|"chat+emotion"| GEM_API
    GEM_API -->|"response"| GEM
    GEM -->|"AI response"| ORCH
    ORCH -->|"synthesize request"| ELE
    ELE -->|"TTS request"| ELE_API
    ELE_API -->|"audio"| ELE
    ELE -->|"audio out"| SPK
    ORCH -->|"display text/emotion"| LCD
    LCD -->|"render"| LCD_HW
    ORCH -->|"alert event"| ALERT
    ALERT -->|"notify"| CARE

    CONFIG_ENV --> ORCH
    CONFIG_PKG --> ORCH
    WEB --> ORCH
    DOC --> ORCH

    click AUDIO "https://github.com/nicksheaharty/bedsidekick-app/blob/main/src/services/audio.js"
    click GEM "https://github.com/nicksheaharty/bedsidekick-app/blob/main/src/services/gemini.js"
    click ELE "https://github.com/nicksheaharty/bedsidekick-app/blob/main/src/services/elevenlabs.js"
    click LCD "https://github.com/nicksheaharty/bedsidekick-app/blob/main/src/services/lcd.js"
    click ORCH "https://github.com/nicksheaharty/bedsidekick-app/blob/main/src/index.js"
    click CONFIG_ENV "https://github.com/nicksheaharty/bedsidekick-app/blob/main/.env"
    click CONFIG_PKG "https://github.com/nicksheaharty/bedsidekick-app/blob/main/package.json"
    click WEB "https://github.com/nicksheaharty/bedsidekick-app/blob/main/public/index.html"
    click DOC "https://github.com/nicksheaharty/bedsidekick-app/blob/main/README.md"

    classDef hardware fill:#c6f6d5,stroke:#2f855a,color:#22543d;
    classDef internal fill:#bee3f8,stroke:#3182ce,color:#2a4365;
    classDef external fill:#fbd38d,stroke:#dd6b20,color:#744210;
    classDef config fill:#e2e8f0,stroke:#4a5568,color:#1a202c;
    classDef frontend fill:#f3e8ff,stroke:#9f7aea,color:#44337a;
    classDef doc fill:#faf089,stroke:#d69e2e,color:#744210
```
