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/speech_piper` — TTS scripts/models → Snapcast
|
||||||
- `sam/voice-assistant` — **this** overview + API contract + clients
|
- `sam/voice-assistant` — **this** overview + API contract + clients
|
||||||
- `sam/family_home_lab` — console portal / dsh
|
- `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