# aws-samples/sample-aws-strands-nova-voice-assistant architecture

> Architecture diagram of the GitHub repository aws-samples/sample-aws-strands-nova-voice-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws-samples/sample-aws-strands-nova-voice-assistant
- Repository: https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant

## Overview

##### Project type and purpose
- This is a full-stack, voice-based AI assistant.
- Frontend: React single-page app using AWS Cloudscape Design for UI and AudioWorklets for real-time audio.
- Backend: Python monolith built on AWS Strands, exposing a WebSocket server, orchestrating multi-agent collaboration, and integrating with AWS services (EC2, SSM, Backup) and AWS Bedrock (Claude 3 Haiku).
- Voice I/O via Amazon Nova Sonic (speech-to-text and text-to-speech).

##### File structure
- **backend/src/voice_based_aws_agent/**
- agents/ (supervisor + specialized agents: ec2_agent, ssm_agent, backup_agent, orchestrator)
- config/ (tool and conversation configuration)
- utils/aws_auth.py (boto3 authentication)
- utils/voice_integration/ (WebSocket server, STT/TTS session management, Nova Sonic bridge)
- main.py (entry point launching the WebSocket and agent framework)
- **frontend/**
- public/ (index.html, Web Manifest, AudioWorklet processor)
- src/ (React components for chat UI and event display, helper modules for audio capture, playback, and WebSocket messaging)
- Deployment scripts: run_backend.sh, run_frontend.sh
- Configuration: requirements.txt, package.json

##### Key insights from README
- Simplified multi-agent architecture with a **Supervisor Agent** routing requests to **Specialized Agents** (EC2, SSM, Backup).
- Real-time voice via **Nova Sonic**.
- Communication channel: **WebSocket server** in the backend, consumed by the React frontend.
- AI inference via **AWS Bedrock Claude 3 Haiku** model calls.
- AWS authentication split: environment variables for Nova Sonic, boto3 profiles for other services.

a. Main components (group into layers):
- User + Browser Client (UI + AudioWorklet)
- Frontend Application (React + WebSocket client)
- Backend Application
– WebSocket Server (voice_integration/server.py)
– Voice Integration Modules (session manager, STT, TTS)
– Multi-Agent Core (orchestrator, supervisor_agent)
– Specialized Agents (ec2_agent, ssm_agent, backup_agent)
– Configuration & Authentication (aws_auth, config files, tool consent)
- External Services
– Amazon Nova Sonic (speech services)
– AWS Bedrock (Claude 3 Haiku inference)
– AWS Service APIs (EC2, SSM, Backup via boto3)
b. Relationships & data flows:
1. User speaks → Browser AudioWorklet captures audio → WebSocket client
2. WebSocket message → Backend WebSocket Server
3. Server forwards raw audio to Nova Sonic STT → text transcript
4. Transcript → Supervisor Agent → invokes AWS Bedrock model for intent/understanding
5. Supervisor routes intent to the correct Specialized Agent
6. Agent calls AWS APIs (boto3) or Bedrock as needed → constructs response
7. Response text → Nova Sonic TTS → audio stream
8. Backend → sends audio chunk via WebSocket → Browser AudioWorklet plays audio
c. Architectural patterns & principles:
- Multi-agent orchestration pattern (Supervisor dispatching to Specialists)
- Single backend monolith (no separate microservices)
- Clear separation of concerns: voice I/O, agent logic, AWS integrations, UI
d. Key technologies/frameworks:
- Python 3.12+, AWS Strands, boto3
- React, AWS Cloudscape Design, AudioWorklet API
- Amazon Nova Sonic, AWS Bedrock Models, WebSocket

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        U["User (Browser)"]:::frontend
        AW["AudioWorklet Processor"]:::frontend
        RH["React SPA"]:::frontend
        WSClient["WebSocket Client"]:::frontend
        U -->|"speaks (PCM audio)"| AW
        AW -->|"audio chunks"| WSClient
        WSClient -->|"WebSocket (audio PCM)"| WS_Server
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        WS_Server["WebSocket Server\n(port 8080)"]:::backend
        SM["STT/TTS Session Manager"]:::backend
        SE["STT/TTS Event Handler"]:::backend
        NSBridge["Nova Sonic Bridge"]:::backend

        subgraph "Agent Orchestration"
            direction TB
            Supervisor["Supervisor Agent"]:::backend
            Orchestrator["Orchestrator Agent"]:::backend
        end

        subgraph "Specialized Agents"
            direction TB
            EC2["EC2 Agent"]:::backend
            SSM["SSM Agent"]:::backend
            Backup["Backup Agent"]:::backend
        end

        subgraph "Config & Auth"
            direction TB
            AWSAuth["AWS Auth Utility"]:::backend
            PromptConsent["Prompt Consent Utility"]:::backend
            Configs["Config Modules"]:::backend
        end

        %% Flows in Backend
        WS_Server -->|"raw audio"| SM
        SM -->|"audio→text"| NSBridge
        NSBridge -->|"transcript"| Supervisor
        Supervisor -->|"dispatch intent"| Orchestrator
        Orchestrator -->|"route to specialist"| EC2
        Orchestrator -->|"route to specialist"| SSM
        Orchestrator -->|"route to specialist"| Backup
        EC2 -->|"boto3 call\n(EC2 API)"| AWS_EC2
        SSM -->|"boto3 call\n(SSM API)"| AWS_SSM
        Backup -->|"boto3 call\n(Backup API)"| AWS_BACKUP
        Supervisor -->|"invoke model"| Bedrock
        Bedrock -->|"intent analysis"| Supervisor
        Supervisor -->|"response text"| NSBridge
        NSBridge -->|"text→audio"| SM
        SM -->|"audio chunks"| WS_Server
    end

    %% External Services
    subgraph "External Services"
        direction TB
        NovaSonic["Amazon Nova Sonic"]:::external
        Bedrock["AWS Bedrock\n(Claude 3 Haiku)"]:::external
        AWS_EC2["AWS EC2 API"]:::external
        AWS_SSM["AWS SSM API"]:::external
        AWS_BACKUP["AWS Backup API"]:::external
    end

    %% Frontend Flow back to user
    WS_Server -->|"WebSocket (audio PCM)"| WSClient
    WSClient -->|"audio playback"| AW
    AW -->|"voice output"| U

    %% Components mapping click events
    click RH "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/frontend/src/App.js"
    click RH "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/frontend/src/VoiceAgent.js"
    click RH "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/frontend/src/components/EventDisplay.js"
    click AW "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/frontend/public/audioPlayerProcessor.worklet.js"
    click AW "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/frontend/src/helper/audioPlayerProcessor.worklet.js"
    click WSClient "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/frontend/src/helper/audioHelper.js"
    click WSClient "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/frontend/src/helper/audioPlayer.js"
    click WSClient "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/frontend/src/helper/s2sEvents.js"
    click main "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/backend/src/voice_based_aws_agent/main.py"
    click WS_Server "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/backend/src/voice_based_aws_agent/utils/voice_integration/server.py"
    click SM "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/backend/src/voice_based_aws_agent/utils/voice_integration/s2s_session_manager.py"
    click SE "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/backend/src/voice_based_aws_agent/utils/voice_integration/s2s_events.py"
    click NSBridge "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/backend/src/voice_based_aws_agent/utils/voice_integration/supervisor_agent_integration.py"
    click AWSAuth "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/backend/src/voice_based_aws_agent/utils/aws_auth.py"
    click PromptConsent "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/backend/src/voice_based_aws_agent/utils/prompt_consent.py"
    click Supervisor "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/backend/src/voice_based_aws_agent/agents/supervisor_agent.py"
    click Orchestrator "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/backend/src/voice_based_aws_agent/agents/orchestrator.py"
    click EC2 "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/backend/src/voice_based_aws_agent/agents/ec2_agent.py"
    click SSM "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/backend/src/voice_based_aws_agent/agents/ssm_agent.py"
    click Backup "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/backend/src/voice_based_aws_agent/agents/backup_agent.py"
    click Configs "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/backend/src/voice_based_aws_agent/config/config.py"
    click Configs "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/backend/src/voice_based_aws_agent/config/conversation_config.py"
    click Configs "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/backend/src/voice_based_aws_agent/config/tool_config.py"
    click SupervisorTool "https://github.com/aws-samples/sample-aws-strands-nova-voice-assistant/blob/main/backend/tools/supervisor_tool.py"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef backend  fill:#c8e6c9,stroke:#43a047,color:#1b5e20
    classDef external fill:#ffe0b2,stroke:#fb8c00,color:#e65100
```
