# aws-samples/sample-nova-sonic-agentic-chatbot architecture

> Architecture diagram of the GitHub repository aws-samples/sample-nova-sonic-agentic-chatbot, 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-nova-sonic-agentic-chatbot
- Repository: https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot

## Overview

##### Project Type and Purpose
- This is a full‐stack demo application combining a Next.js/TypeScript/Tailwind CSS frontend with a FastAPI/Python backend.
- Purpose: Showcase Nova Sonic’s modular tool system, real‐time audio capture/playback, and dynamic UI rendering for dual results (model context + UI payload).

##### Top‐Level Components
- Frontend (frontend/)
- Next.js App Router (`app/`), React components (`components/`), global styles, config, and utility functions.
- UI components broken out into:
– Apps (e.g. EchoApp)
– Tool‐Outputs for each UI result type (Text, Card, Image, Video, PDF…)
– Base UI primitives (Button, Slider, Card…)
- WebSocket client + audio capture via MediaRecorder APIs.
- Backend (backend/)
- FastAPI application (`main.py`), WebSocket endpoint for voice sessions.
- `api/apps/echo.py` sample endpoint.
- Nova Sonic integration (`nova_sonic_simple.py`) that drives conversation & delegates to tools.
- Modular Tool System:
– Base classes & registry (`tools/base/`)
– Category folders (`tools/categories/{utility,media,order}`)
– Tool Manager (`tool_manager.py`) that discovers and registers tools.
- Optional debug audio storage (`backend/debug_audio/`).
- External/Infrastructure
- Nova Sonic LLM or voice‐AI service (via `nova_sonic_simple.py`).
- Client browser.
- Local filesystem storage (debug audio).

##### Key Relationships & Data Flows
1. User interacts in browser → clicks Power → WebSocket connection established to FastAPI.
2. Click Mic → MediaRecorder starts streaming audio chunks over WebSocket.
3. FastAPI receives audio stream → passes to Nova Sonic service wrapper.
4. Nova Sonic orchestrates tool invocation:
- Tool Manager selects appropriate tool(s) from registry.
- Each tool `execute()` returns `{ model_result, ui_result }`.
5. Backend merges results → streams dual‐payload back to frontend over WebSocket.
6. Frontend receives `ui_result.type` → renders using appropriate React component.
7. If `SAVE_DEBUG_AUDIO=true`, raw audio saved to `backend/debug_audio/`.

##### Architectural Patterns & Design Principles
- Separation of Concerns: UI vs API vs Tool logic.
- Plugin pattern: Tools register via a central registry.
- Async non‐blocking pipelines: FastAPI + async tool execution.
- Dual‐result pattern: decouple model context from UI rendering payload.
- Component‐based UI: React + Next.js for dynamic rendering based on `ui_result.type`.

- Browser (Client)
- UI Layer: React/Next.js, components, MediaRecorder, WebSocket client.
- Frontend Server (Next.js)
- App Router, Static Assets, WebSocket proxy (if used).
- Backend Server (FastAPI)
- WebSocket endpoint
- HTTP API endpoints
- Nova Sonic service integration
- Tool Manager & Tool Registry
- Tool Categories (Utility, Media, Order)
- Debug Audio Storage
- External Service
- Nova Sonic LLM/Voice Engine
- Data Store (optional)
- Filesystem for debug audio.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Browser (Client)"
        Browser["Browser UI"]:::frontend
        AudioCaps["MediaRecorder & WebSocket Client"]:::frontend
    end

    subgraph "Next.js Server"
        AppRouter["App Router\n(Next.js, TS, Tailwind)"]:::frontend
        Globals["globals.css, layout.tsx, page.tsx"]:::frontend
        ReactComp["EchoApp.tsx"]:::frontend
        ToolOutputs["ToolOutput Components"]:::frontend
        UIPrims["UI Primitives"]:::frontend
        ConfigUtils["Config & Utils"]:::frontend
    end

    subgraph "FastAPI Server"
        FastAPI["FastAPI App\n(main.py)"]:::backend
        EchoAPI["Echo API\n(echo.py)"]:::backend
        WS["WebSocket Endpoint"]:::backend
        NovaSonic["NovaSonic Wrapper\n(nova_sonic_simple.py)"]:::backend
        subgraph "Tool System"
            ToolMgr["Tool Manager\n(tool_manager.py)"]:::backend
            Registry["Registry\n(registry.py)"]:::backend
            BaseTool["BaseTool\n(tool.py)"]:::backend
            subgraph "Categories"
                MediaTools["Media Tools"]:::backend
                OrderTools["Order Tools"]:::backend
                UtilityTools["Utility Tools"]:::backend
            end
        end
        DebugFS["Debug Audio Storage"]:::storage
    end

    External["NovaSonic AI Service"]:::external

    Browser -->|"HTTP/WebSocket"| AppRouter
    Browser --> AudioCaps
    AudioCaps -->|"WebSocket stream (audio chunks)"| WS
    AppRouter -->|"Proxy to FastAPI"| WS
    WS -->|"RPC/SDK call"| NovaSonic
    NovaSonic -->|"orchestrate tools"| ToolMgr
    ToolMgr -->|"select tools"| Registry
    Registry --> BaseTool
    BaseTool --> MediaTools
    BaseTool --> OrderTools
    BaseTool --> UtilityTools
    ToolMgr -->|"return results"| NovaSonic
    NovaSonic --> FastAPI
    FastAPI -->|"JSON {ui_result}"| Browser
    FastAPI -->|"write .wav if DEBUG"| DebugFS
    FastAPI -->|"call NovaSonic AI"| External

    click AppRouter "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/tree/main/frontend/app/"
    click Globals "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/frontend/app/globals.css"
    click Globals "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/frontend/app/layout.tsx"
    click Globals "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/frontend/app/page.tsx"
    click ReactComp "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/frontend/components/apps/EchoApp.tsx"
    click AudioCaps "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/frontend/components/audio-capture.tsx"
    click AudioCaps "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/frontend/components/audio-capture-mediarecorder.tsx"
    click AudioCaps "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/frontend/components/audio-playback.tsx"
    click ToolOutputs "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/frontend/components/tool-outputs/ToolOutput.tsx"
    click UIPrims "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/frontend/components/ui/button.tsx"
    click UIPrims "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/frontend/components/ui/slider.tsx"
    click UIPrims "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/frontend/components/ui/card.tsx"
    click UIPrims "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/frontend/components/ui/avatar.tsx"
    click UIPrims "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/frontend/components/ui/badge.tsx"
    click UIPrims "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/frontend/components/ui/separator.tsx"
    click ConfigUtils "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/frontend/config/tool-outputs.ts"
    click ConfigUtils "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/frontend/lib/utils.ts"
    click FastAPI "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/backend/main.py"
    click EchoAPI "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/backend/api/apps/echo.py"
    click NovaSonic "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/backend/nova_sonic_simple.py"
    click Registry "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/backend/tools/base/registry.py"
    click ToolMgr "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/backend/tools/tool_manager.py"
    click BaseTool "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/backend/tools/base/tool.py"
    click MediaTools "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/backend/tools/categories/media/sample_image_tool.py"
    click MediaTools "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/backend/tools/categories/media/sample_pdf_tool.py"
    click MediaTools "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/backend/tools/categories/media/sample_video_tool.py"
    click OrderTools "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/backend/tools/categories/order/track_order_tool.py"
    click UtilityTools "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/blob/main/backend/tools/categories/utility/datetime_tool.py"
    click DebugFS "https://github.com/aws-samples/sample-nova-sonic-agentic-chatbot/tree/main/backend/debug_audio/"

    classDef frontend fill:#E0F7FA,stroke:#006064,color:#004D40
    classDef backend fill:#E8F5E9,stroke:#1B5E20,color:#0D5302
    classDef external fill:#FFF3E0,stroke:#E65100,color:#BF360C
    classDef storage fill:#FFFDE7,stroke:#F9A825,color:#F57F17
```
