docs: add voice-assistant system map (Archify HTML + Mermaid source)
This commit is contained in:
283
docs/archify/voice-assistant.architecture.json
Normal file
283
docs/archify/voice-assistant.architecture.json
Normal file
@@ -0,0 +1,283 @@
|
||||
{
|
||||
"schema_version": 1,
|
||||
"diagram_type": "architecture",
|
||||
"meta": {
|
||||
"title": "Jervis Voice Assistant \u2014 System Map",
|
||||
"quality_profile": "showcase"
|
||||
},
|
||||
"components": [
|
||||
{
|
||||
"id": "esp32",
|
||||
"type": "frontend",
|
||||
"label": "ESP32-S3",
|
||||
"sublabel": "wake word \u00b7 mic \u00b7 LED",
|
||||
"pos": [
|
||||
40,
|
||||
300
|
||||
],
|
||||
"size": [
|
||||
126,
|
||||
62
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "mqtt",
|
||||
"type": "messagebus",
|
||||
"label": "MQTT",
|
||||
"sublabel": "mosquitto :1883",
|
||||
"pos": [
|
||||
240,
|
||||
300
|
||||
],
|
||||
"size": [
|
||||
124,
|
||||
60
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "whisper",
|
||||
"type": "backend",
|
||||
"label": "Whisper STT",
|
||||
"sublabel": "faster-whisper",
|
||||
"pos": [
|
||||
440,
|
||||
300
|
||||
],
|
||||
"size": [
|
||||
126,
|
||||
60
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "agent",
|
||||
"type": "backend",
|
||||
"label": "Jervis Agent",
|
||||
"sublabel": "FastAPI :8501",
|
||||
"pos": [
|
||||
645,
|
||||
300
|
||||
],
|
||||
"size": [
|
||||
130,
|
||||
62
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "ha",
|
||||
"type": "external",
|
||||
"label": "Home Assistant",
|
||||
"sublabel": ".30 :8123",
|
||||
"pos": [
|
||||
645,
|
||||
95
|
||||
],
|
||||
"size": [
|
||||
142,
|
||||
62
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "omniroute",
|
||||
"type": "cloud",
|
||||
"label": "OmniRoute",
|
||||
"sublabel": "LLM gateway :20129",
|
||||
"pos": [
|
||||
890,
|
||||
95
|
||||
],
|
||||
"size": [
|
||||
136,
|
||||
62
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "mopidy",
|
||||
"type": "external",
|
||||
"label": "Mopidy \u00b7 Spotify",
|
||||
"sublabel": "music :6600",
|
||||
"pos": [
|
||||
890,
|
||||
300
|
||||
],
|
||||
"size": [
|
||||
140,
|
||||
60
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "apprise",
|
||||
"type": "external",
|
||||
"label": "Apprise",
|
||||
"sublabel": "notifications .35",
|
||||
"pos": [
|
||||
890,
|
||||
505
|
||||
],
|
||||
"size": [
|
||||
126,
|
||||
60
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "piper",
|
||||
"type": "backend",
|
||||
"label": "Piper TTS",
|
||||
"sublabel": ":10200",
|
||||
"pos": [
|
||||
890,
|
||||
610
|
||||
],
|
||||
"size": [
|
||||
118,
|
||||
60
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "snapcast",
|
||||
"type": "messagebus",
|
||||
"label": "Snapcast",
|
||||
"sublabel": "multi-room :1780",
|
||||
"pos": [
|
||||
645,
|
||||
560
|
||||
],
|
||||
"size": [
|
||||
130,
|
||||
62
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "speakers",
|
||||
"type": "external",
|
||||
"label": "House Speakers",
|
||||
"sublabel": "whole home",
|
||||
"pos": [
|
||||
1100,
|
||||
610
|
||||
],
|
||||
"size": [
|
||||
124,
|
||||
60
|
||||
]
|
||||
}
|
||||
],
|
||||
"boundaries": [
|
||||
{
|
||||
"kind": "region",
|
||||
"label": "On-device",
|
||||
"wraps": [
|
||||
"esp32"
|
||||
]
|
||||
},
|
||||
{
|
||||
"kind": "region",
|
||||
"label": "Home lab (.13 \u00b7 .30 \u00b7 .35)",
|
||||
"wraps": [
|
||||
"mqtt",
|
||||
"whisper",
|
||||
"agent",
|
||||
"ha",
|
||||
"omniroute",
|
||||
"mopidy",
|
||||
"apprise",
|
||||
"piper",
|
||||
"snapcast",
|
||||
"speakers"
|
||||
]
|
||||
}
|
||||
],
|
||||
"connections": [
|
||||
{
|
||||
"id": "esp32-mqtt",
|
||||
"from": "esp32",
|
||||
"to": "mqtt",
|
||||
"label": "audio stream",
|
||||
"variant": "emphasis"
|
||||
},
|
||||
{
|
||||
"id": "mqtt-whisper",
|
||||
"from": "mqtt",
|
||||
"to": "whisper",
|
||||
"label": "speech frames",
|
||||
"variant": "dashed"
|
||||
},
|
||||
{
|
||||
"id": "whisper-agent",
|
||||
"from": "whisper",
|
||||
"to": "agent",
|
||||
"label": "transcript"
|
||||
},
|
||||
{
|
||||
"id": "agent-ha",
|
||||
"from": "agent",
|
||||
"to": "ha",
|
||||
"label": "control \u00b7 todo \u00b7 timers",
|
||||
"fromSide": "top",
|
||||
"toSide": "bottom",
|
||||
"labelDx": -55
|
||||
},
|
||||
{
|
||||
"id": "agent-omni",
|
||||
"from": "agent",
|
||||
"to": "omniroute",
|
||||
"label": "intent / Q&A",
|
||||
"fromSide": "top",
|
||||
"toSide": "bottom"
|
||||
},
|
||||
{
|
||||
"id": "agent-mopidy",
|
||||
"from": "agent",
|
||||
"to": "mopidy",
|
||||
"label": "play \u00b7 pause \u00b7 volume",
|
||||
"variant": "dashed"
|
||||
},
|
||||
{
|
||||
"id": "agent-apprise",
|
||||
"from": "agent",
|
||||
"to": "apprise",
|
||||
"label": "family messages",
|
||||
"variant": "dashed",
|
||||
"fromSide": "bottom",
|
||||
"toSide": "top"
|
||||
},
|
||||
{
|
||||
"id": "agent-snap",
|
||||
"from": "agent",
|
||||
"to": "snapcast",
|
||||
"label": "reply text",
|
||||
"fromSide": "bottom",
|
||||
"toSide": "top",
|
||||
"labelDy": 40,
|
||||
"labelDx": -55
|
||||
},
|
||||
{
|
||||
"id": "snap-piper",
|
||||
"from": "snapcast",
|
||||
"to": "piper",
|
||||
"label": "synthesize speech",
|
||||
"variant": "dashed",
|
||||
"labelAt": [
|
||||
920,
|
||||
684
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "piper-snap",
|
||||
"from": "piper",
|
||||
"to": "snapcast",
|
||||
"label": "speech wav",
|
||||
"labelDy": -25
|
||||
},
|
||||
{
|
||||
"id": "snap-speakers",
|
||||
"from": "snapcast",
|
||||
"to": "speakers",
|
||||
"label": "audio out",
|
||||
"variant": "emphasis",
|
||||
"labelAt": [
|
||||
1020,
|
||||
693
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -104,3 +104,14 @@ Also fixed along the way: mopidy-local disabled (empty `library.db` crashed sear
|
||||
- `sam/speech_piper` — TTS scripts/models → Snapcast
|
||||
- `sam/voice-assistant` — **this** overview + API contract + clients
|
||||
- `sam/family_home_lab` — console portal / dsh
|
||||
---
|
||||
|
||||
## Diagrams
|
||||
|
||||
- **Interactive map** (Archify HTML, pan/zoom/search/dark-light): [`voice-assistant-map.html`](./voice-assistant-map.html)
|
||||
- Published live: <https://maps.lab.audasmedia.com.au/homeassistant/docs/voice-assistant-map.html>
|
||||
- **Mermaid source**: [`voice-assistant.mmd`](./voice-assistant.mmd) · rendered **SVG**: [`diagrams/voice-assistant.svg`](./diagrams/voice-assistant.svg)
|
||||
- **Archify JSON IR** (single source of truth for the interactive map): [`archify/voice-assistant.architecture.json`](./archify/voice-assistant.architecture.json)
|
||||
|
||||
> Regenerate the interactive map from the JSON:
|
||||
> `node ~/.agents/skills/archify/bin/archify.mjs deliver architecture docs/archify/voice-assistant.architecture.json docs/voice-assistant-map.html --quality showcase --json`
|
||||
|
||||
13702
docs/voice-assistant-map.html
Normal file
13702
docs/voice-assistant-map.html
Normal file
File diff suppressed because it is too large
Load Diff
29
docs/voice-assistant.mmd
Normal file
29
docs/voice-assistant.mmd
Normal file
@@ -0,0 +1,29 @@
|
||||
flowchart LR
|
||||
subgraph OnDevice["On-device"]
|
||||
ESP32[ESP32-S3<br/>wake word · mic · LED]
|
||||
end
|
||||
|
||||
subgraph Lab["Home lab (.13 · .30 · .35)"]
|
||||
MQTT[(MQTT<br/>mosquitto :1883)]
|
||||
WHISPER[Whisper STT<br/>faster-whisper]
|
||||
AGENT[Jervis Agent<br/>FastAPI :8501]
|
||||
HA[Home Assistant<br/>.30 :8123]
|
||||
OMNI[OmniRoute<br/>LLM gateway :20129]
|
||||
MOPIDY[Mopidy · Spotify<br/>music :6600]
|
||||
APPRISE[Apprise<br/>notifications .35]
|
||||
SNAP[Snapcast<br/>multi-room :1780]
|
||||
PIPER[Piper TTS<br/>:10200]
|
||||
SPEAKERS[House Speakers<br/>whole home]
|
||||
end
|
||||
|
||||
ESP32 -->|audio stream| MQTT
|
||||
MQTT -.->|speech frames| WHISPER
|
||||
WHISPER -->|transcript| AGENT
|
||||
AGENT -->|control · todo · timers| HA
|
||||
AGENT -->|intent / Q&A| OMNI
|
||||
AGENT -.->|play · pause · volume| MOPIDY
|
||||
AGENT -.->|family messages| APPRISE
|
||||
AGENT -->|reply text| SNAP
|
||||
SNAP -.->|synthesize speech| PIPER
|
||||
PIPER -->|speech wav| SNAP
|
||||
SNAP -->|audio out| SPEAKERS
|
||||
Reference in New Issue
Block a user