# peter-dated-projects/s.o.n.a. architecture

> Architecture diagram of the GitHub repository peter-dated-projects/s.o.n.a., generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/peter-dated-projects/s.o.n.a.
- Repository: https://github.com/peter-dated-projects/s.o.n.a.

## Overview

##### Project type and purpose
- From the file tree and README, S.O.N.A. is a full-stack voice assistant application (“Semantic Operational & Natural Assistant”).
- It comprises a Python-based backend exposing STT, streaming, storage APIs plus integrations (MCP functions, Whisper core, wake-word detection) and a TypeScript/Next.js frontend serving a web UI.

##### File structure
Top-level split:
- backend/ – Python backend
– api/ (REST/streaming/STT blueprints)
– assets/ (models: Porcupine wake-word, Whisper data)
– mcp_function/ (microservices‐style clients & servers for Google Workspace, Spotify, System, Terminal)
– models/ (ORM/data models)
– source/ (core request handlers, main entry-points)
– main.py, backend.py (application bootstrap)
– run_backend.sh, requirements.txt
- frontend/ – Next.js application
– src/app/ (pages, layouts, global CSS)
– public/ (static assets)
– config (ESLint, tsconfig, next.config)
- docs/, tests, scripts (test_psql.py, verify.py)

##### README for additional insights
- The README lists three primary API domains:
- /stt/* – Speech-to-Text
- /storage/* – Database operations
- /streaming/* – Real-time audio streaming
- It describes environment setup, Python 3.10, and points to the main backend entrypoint at backend/main.py

##### Detailed capture of architectural elements
– Inside the backend, subdivide into:
- Core pipeline (wake-word → STT → NLP/Intent → Response)
- Data layer (message store, session store)
- Integration layer (MCP functions as microservices)
- Asset store (models for wake-word, Whisper)
– Show optional dev/test scripts off to the side, illustrating how they target the APIs or database

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        UI["Next.js Web Client"]:::ui
    end

    %% Backend API Gateway
    subgraph "Backend Layer"
        direction TB

        APIGW["API Gateway\n(Flask/FastAPI)"]:::api

        %% Core Services
        subgraph "API Services"
            direction TB
            STT["STT Service"]:::service
            STREAM["Streaming Service"]:::service
            STORAGE["Storage Service\n(Database API)"]:::service
        end

        %% Database Layer
        subgraph "Database Layer"
            direction TB
            DB["ORM Models & Storage"]:::data
        end

        %% MCP Function Layer
        subgraph "MCP Function Layer"
            direction TB
            subgraph "Clients"
                direction TB
                CL_CLIENT["MCP Client"]:::service
            end
            subgraph "Servers"
                direction TB
                CL_GOOGLE["Google Workspace Server"]:::ext
                CL_SPOTIFY["Spotify Server"]:::ext
                CL_SYSTEM["System Server"]:::ext
                CL_TERMINAL["Terminal Server"]:::ext
            end
        end

        %% Asset Store
        subgraph "Asset & Model Store"
            direction TB
            WAKE["Wake-word Detector"]:::data
            WHISPER["External AI Model"]:::data
            STATIC["Static Assets"]:::data
        end
    end

    %% Dev/Test Utilities
    subgraph "Dev/Test Utilities"
        direction TB
        TEST["Test & Verification Scripts"]:::util
    end

    %% External Flow
    UI -->|HTTP/WS| APIGW
    APIGW -->|REST/STT| STT
    APIGW -->|REST/Storage| STORAGE
    APIGW -->|WS Streaming| STREAM
    APIGW -->|RPC| CL_CLIENT
    APIGW -->|DB Queries| DB

    STT -->|loads model| WHISPER
    WAKE -->|triggers| STT
    STREAM -->|push audio| UI
    CL_CLIENT -->|invokes| CL_GOOGLE
    CL_CLIENT -->|invokes| CL_SPOTIFY
    CL_CLIENT -->|invokes| CL_SYSTEM
    CL_CLIENT -->|invokes| CL_TERMINAL

    TEST -->|executes against| APIGW
    TEST -->|checks| DB

    %% Click Events
    click UI "https://github.com/peter-dated-projects/s.o.n.a./tree/main/frontend/src/app/"
    click UI "https://github.com/peter-dated-projects/s.o.n.a./tree/main/frontend/public/"
    click UI "https://github.com/peter-dated-projects/s.o.n.a./blob/main/frontend/package.json"
    click UI "https://github.com/peter-dated-projects/s.o.n.a./blob/main/frontend/next.config.ts"

    click APIGW "https://github.com/peter-dated-projects/s.o.n.a./blob/main/backend/main.py"
    click APIGW "https://github.com/peter-dated-projects/s.o.n.a./blob/main/backend/backend.py"

    click STT "https://github.com/peter-dated-projects/s.o.n.a./blob/main/backend/api/stt.py"
    click STT "https://github.com/peter-dated-projects/s.o.n.a./blob/main/backend/api/stt.md"
    click STT "https://github.com/peter-dated-projects/s.o.n.a./blob/main/backend/api/whispercorehandler.py"

    click STREAM "https://github.com/peter-dated-projects/s.o.n.a./blob/main/backend/api/messaging.py"
    click STREAM "https://github.com/peter-dated-projects/s.o.n.a./blob/main/backend/api/streaming.md"

    click DB "https://github.com/peter-dated-projects/s.o.n.a./blob/main/backend/models/message.py"
    click DB "https://github.com/peter-dated-projects/s.o.n.a./blob/main/backend/models/__init__.py"

    click CL_CLIENT "https://github.com/peter-dated-projects/s.o.n.a./blob/main/backend/mcp_function/client/client.py"
    click CL_CLIENT "https://github.com/peter-dated-projects/s.o.n.a./blob/main/backend/mcp_function/client/main.py"
    click CL_GOOGLE "https://github.com/peter-dated-projects/s.o.n.a./blob/main/backend/mcp_function/server/googletool-server.py"
    click CL_SPOTIFY "https://github.com/peter-dated-projects/s.o.n.a./blob/main/backend/mcp_function/server/spotify-server.py"
    click CL_SYSTEM "https://github.com/peter-dated-projects/s.o.n.a./blob/main/backend/mcp_function/server/system-server.py"
    click CL_TERMINAL "https://github.com/peter-dated-projects/s.o.n.a./blob/main/backend/mcp_function/server/terminal-server.py"
    click CL_CLIENT "https://github.com/peter-dated-projects/s.o.n.a./blob/main/backend/mcp_function/server/main.py"

    click WAKE "https://github.com/peter-dated-projects/s.o.n.a./blob/main/backend/assets/porcupine/Hey-SONA_en_mac_v3_0_0.ppn"
    click WHISPER "https://github.com/peter-dated-projects/s.o.n.a./tree/main/backend/assets/models/"
    click WHISPER "https://github.com/peter-dated-projects/s.o.n.a./blob/main/backend/source/whispercore_main.py"
    click STATIC "https://github.com/peter-dated-projects/s.o.n.a./tree/main/backend/assets/models/"
    click STATIC "https://github.com/peter-dated-projects/s.o.n.a./tree/main/backend/assets/porcupine/"

    click TEST "https://github.com/peter-dated-projects/s.o.n.a./blob/main/test_psql.py"
    click TEST "https://github.com/peter-dated-projects/s.o.n.a./blob/main/verify.py"
    click TEST "https://github.com/peter-dated-projects/s.o.n.a./blob/main/test.py"
    click TEST "https://github.com/peter-dated-projects/s.o.n.a./blob/main/backend/run_backend.sh"

    %% Styles
    classDef ui fill:#AEDBFF,stroke:#0366D6,color:#000
    classDef api fill:#C8E6C9,stroke:#2E7D32,color:#000
    classDef service fill:#DCEDC8,stroke:#558B2F,color:#000
    classDef data fill:#FFE0B2,stroke:#EF6C00,color:#000
    classDef ext fill:#E1BEE7,stroke:#7B1FA2,color:#000
    classDef util fill:#E0E0E0,stroke:#616161,color:#000
```
