# crushn8r/gopod architecture

> Architecture diagram of the GitHub repository crushn8r/gopod, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/crushn8r/gopod
- Repository: https://github.com/crushn8r/gopod

## Overview

1. **Overall shape**
   - This repo is a **local-first robot session engine** built around **Wire-Pod** and split into two main concerns:
     - `goverlord/gomads/` = the domain logic and device/robot interaction layers.
     - `goverlord/runtime/` = the pruned, interview-scoped execution path used for the GOPOD demo and safety wrappers.

2. **External control plane: Wire-Pod**
   - The system is not a standalone app; it **attaches to Wire-Pod** as the robot server and intent router.
   - The wake phrase and custom intent path are handled by Wire-Pod, which then **execs out** to a Python runner for the `GOPOD_YOURSELF` flow.
   - README also shows the robot control API boundary: **assume behavior control → say_text → release behavior control**.

3. **Intent entrypoint and contract boundary**
   - `goverlord/runtime/wire-pod/wirepod_intents/gopod_yourself_001/` is the intent scaffold.
   - It contains:
     - the intent definition JSON,
     - intent docs and operator phrase maps,
     - armed-mode and transport-rule contract docs,
     - a `gopod_yourself_dry_run.py` script for the intent path.
   - This directory is the main **handoff boundary** between Wire-Pod and the GOPOD session logic.

4. **Low-level input subsystem**
   - `goverlord/gomads/low_level/input_gomad/` handles **push-to-talk / keypad routing**.
   - Key files:
     - `input_event_logic.py`
     - `contracts/input_contract.py`
     - `input_routes.json`
     - `wiring/input_bridge.py`
   - README ties this to the numpad controls:
     - **KP1** routes to Doc,
     - **KP2** routes to Pip,
     - **KP0 x3** exits.

5. **Robot interface subsystem**
   - `goverlord/gomads/low_level/robot_interface_gomad/` is the robot-facing speech/expression layer.
   - It includes:
     - `robot_speech_logic.py`
     - `code/robot_expression_parser_001.py`
     - `contracts/robot_interface_contract.py`
     - `robot_interface_config.json`
     - `wiring/robot_interface_bridge.py`
   - This is the translation layer from session intent/output into **robot-safe speech and expression commands**.

6. **Robot I/O safety and text hygiene**
   - `goverlord/runtime/robot/robot_io/` is a separate safety boundary around outbound speech text.
   - Components include:
     - `robot_safe_packet_guard.py`
     - `outbound_text_filter_001.py`
     - `text_replacement_filter.py`
   - `goverlord/runtime/prelaunch/replacement_rules_001.json` supplies prelaunch text substitutions.
   - Architecturally, this layer prevents raw model output from going directly to the robot.

7. **Voice verification and TTS status**
   - `goverlord/runtime/voice/` contains the local audio verification/support pieces:
     - `audio_proof_ladder_001.py`
     - `gopod_audio_execution_verifier_001.py`
     - `local_tts_voice_registry_001/interview_status_kokoro_announcer_001.py`
     - `test_gopod_audio_execution_verifier_001.py`
   - This is not the main STT/LLM engine; it is the **runtime verification and announcement layer** around voice execution.

8. **End-to-end live session flow**
   - The README’s live path is:
     - **Wire-Pod wake phrase**
     - **custom intent match**
     - **exec into GOPOD runner**
     - **PTT loop**
     - **local STT with Vosk**
     - **local LLM with Ollama**
     - **Wire-Pod SDK speech back to the robot**
   - The repo itself mainly contains the **contract, bridge, and safety layers** for that flow rather than the full live runner.

9. **Two-robot session model**
   - The system treats the robots as role-separated endpoints:
     - **Doc** = doctrine/canonical speaker
     - **Pip** = confused sidekick / audience proxy
   - The routing logic in the input and robot-interface layers is what maps the active key/intent to the correct voice persona.

10. **Repo boundaries and what is external**
   - This repo deliberately depends on external runtime pieces:
     - **Wire-Pod** for intent dispatch and robot API control,
     - **Ollama** for local LLM generation,
     - **Vosk** for local STT,
     - the actual live interview runner is described as living in the external Wire-Pod tree.
   - That separation is important for the architecture diagram: this repo is the **GOPOD control/scaffold layer**, not the full robot stack.

11. **Documentation as architecture**
   - The many `README.md` and `contract` files are part of the design itself.
   - They define expected behavior for the bridges, intent boundaries, and robot-safe execution rules.
   - In practice, they act like a **specification layer** for the runtime code.

12. **Utility / ops support**
   - `goshot.sh` is a repo snapshot utility.
   - Its presence reinforces that this codebase is being managed as a **stateful engineering artifact** with repeatable capture of the current truth, not just an application source tree.

Main entry points: [`goverlord/README.md`](https://github.com/crushn8r/gopod/blob/main/goverlord/README.md) (Goverlord README), [`goverlord/runtime/voice/gopod_audio_execution_verifier_001.py`](https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/voice/gopod_audio_execution_verifier_001.py) (Audio verifier), [`goverlord/gomads/low_level/input_gomad/input_event_logic.py`](https://github.com/crushn8r/gopod/blob/main/goverlord/gomads/low_level/input_gomad/input_event_logic.py) (Input logic), [`goverlord/gomads/low_level/robot_interface_gomad/robot_speech_logic.py`](https://github.com/crushn8r/gopod/blob/main/goverlord/gomads/low_level/robot_interface_gomad/robot_speech_logic.py) (Speech logic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo_overview["Repo overview"]
  node_repo_readme["README<br/>repo spec<br/>[README.md]"]
  node_gopod_readme["Goverlord README<br/>architecture notes<br/>[README.md]"]
  node_snapshot_tool["goshot.sh<br/>ops utility<br/>[goshot.sh]"]
end

subgraph group_gomads_input["Input routing"]
  node_input_logic["Input logic<br/>keypad router"]
  node_input_bridge["Input bridge<br/>[input_bridge.py]"]
  node_input_contract["Input contract<br/>[input_contract.py]"]
end

subgraph group_gomads_robot["Robot interface"]
  node_robot_speech["Speech logic<br/>speech mapper"]
  node_expr_parser["Expr parser<br/>expression parser"]
  node_robot_bridge["Robot bridge"]
  node_robot_contract["Robot contract"]
end

subgraph group_runtime_robot_io["Robot safety"]
  node_safe_guard["Safe guard<br/>text safety"]
  node_text_filter["Text filter<br/>sanitizer"]
  node_replacement_filter["Replacement filter<br/>rewrite filter"]
  node_replacement_rules["Rules<br/>prelaunch config"]
end

subgraph group_runtime_voice["Voice runtime"]
  node_audio_verifier["Audio verifier<br/>execution verifier"]
  node_audio_ladder["Proof ladder<br/>verification ladder"]
  node_tts_announcer["TTS announcer<br/>voice registry"]
end

subgraph group_wirepod_intent["Wire-Pod intent"]
  node_intent_scaffold["GOPOD intent<br/>Wire-Pod intent"]
  node_intent_runner["Dry run<br/>intent runner"]
  node_armed_contract["Armed mode<br/>contract"]
  node_transport_rules["Transport rules<br/>contract"]
  node_phrase_map["Phrase map<br/>operator map"]
end

subgraph group_external["External runtime"]
  node_external_wirepod["Wire-Pod<br/>external control plane"]
  node_external_llm[("Ollama<br/>external model")]
  node_external_stt[("Vosk<br/>external STT")]
end

node_repo_readme -->|"describes control plane"| node_external_wirepod
node_repo_readme -->|"documents ptt flow"| node_input_logic
node_repo_readme -->|"documents safety"| node_safe_guard
node_intent_scaffold -->|"executes"| node_intent_runner
node_external_wirepod -->|"dispatches intent"| node_intent_scaffold
node_armed_contract -.->|"constrains"| node_intent_runner
node_transport_rules -.->|"constrains"| node_intent_runner
node_phrase_map -.->|"maps phrases"| node_intent_scaffold
node_input_bridge -->|"routes events"| node_input_logic
node_input_contract -.->|"defines contract"| node_input_logic
node_input_logic -->|"selects persona"| node_robot_bridge
node_robot_bridge -->|"invokes"| node_robot_speech
node_robot_contract -.->|"defines contract"| node_robot_speech
node_expr_parser -->|"parses markers"| node_robot_speech
node_robot_speech -->|"emits text"| node_safe_guard
node_replacement_rules -.->|"supplies rules"| node_replacement_filter
node_safe_guard -->|"filters"| node_text_filter
node_text_filter -->|"rewrites"| node_replacement_filter
node_replacement_filter -->|"returns speech"| node_external_wirepod
node_audio_ladder -->|"feeds checks"| node_audio_verifier
node_tts_announcer -.->|"announces status"| node_audio_verifier
node_audio_verifier -.->|"verifies via"| node_external_stt
node_audio_verifier -.->|"verifies via"| node_external_llm
node_gopod_readme -->|"documents subsystem"| node_input_bridge
node_gopod_readme -->|"documents subsystem"| node_robot_bridge
node_gopod_readme -->|"documents safety"| node_safe_guard
node_gopod_readme -->|"documents handoff"| node_intent_scaffold

click node_repo_readme "https://github.com/crushn8r/gopod/blob/main/README.md"
click node_gopod_readme "https://github.com/crushn8r/gopod/blob/main/goverlord/README.md"
click node_snapshot_tool "https://github.com/crushn8r/gopod/blob/main/goshot.sh"
click node_input_logic "https://github.com/crushn8r/gopod/blob/main/goverlord/gomads/low_level/input_gomad/input_event_logic.py"
click node_input_bridge "https://github.com/crushn8r/gopod/blob/main/goverlord/gomads/low_level/input_gomad/wiring/input_bridge.py"
click node_input_contract "https://github.com/crushn8r/gopod/blob/main/goverlord/gomads/low_level/input_gomad/contracts/input_contract.py"
click node_robot_speech "https://github.com/crushn8r/gopod/blob/main/goverlord/gomads/low_level/robot_interface_gomad/robot_speech_logic.py"
click node_expr_parser "https://github.com/crushn8r/gopod/blob/main/goverlord/gomads/low_level/robot_interface_gomad/code/robot_expression_parser_001.py"
click node_robot_bridge "https://github.com/crushn8r/gopod/blob/main/goverlord/gomads/low_level/robot_interface_gomad/wiring/robot_interface_bridge.py"
click node_robot_contract "https://github.com/crushn8r/gopod/blob/main/goverlord/gomads/low_level/robot_interface_gomad/contracts/robot_interface_contract.py"
click node_safe_guard "https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/robot/robot_io/robot_safe_packet_guard.py"
click node_text_filter "https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/robot/robot_io/outbound_text_filter_001.py"
click node_replacement_filter "https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/robot/robot_io/text_replacement_filter.py"
click node_replacement_rules "https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/prelaunch/replacement_rules_001.json"
click node_audio_verifier "https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/voice/gopod_audio_execution_verifier_001.py"
click node_audio_ladder "https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/voice/audio_proof_ladder_001.py"
click node_tts_announcer "https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/voice/local_tts_voice_registry_001/interview_status_kokoro_announcer_001.py"
click node_intent_scaffold "https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/wire-pod/wirepod_intents/gopod_yourself_001/gopod_yourself_intent_001.json"
click node_intent_runner "https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/wire-pod/wirepod_intents/gopod_yourself_001/gopod_yourself_dry_run.py"
click node_armed_contract "https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/wire-pod/wirepod_intents/gopod_yourself_001/gopod_armed_mode_contract_001.md"
click node_transport_rules "https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/wire-pod/wirepod_intents/gopod_yourself_001/do_not_invent_transport_rules_001.md"
click node_phrase_map "https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/wire-pod/wirepod_intents/gopod_yourself_001/operator_phrase_map_001.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_repo_readme,node_gopod_readme,node_snapshot_tool,node_external_wirepod,node_external_llm,node_external_stt toneBlue
class node_input_logic,node_input_bridge,node_input_contract toneAmber
class node_robot_speech,node_expr_parser,node_robot_bridge,node_robot_contract toneMint
class node_safe_guard,node_text_filter,node_replacement_filter,node_replacement_rules toneRose
class node_audio_verifier,node_audio_ladder,node_tts_announcer toneIndigo
class node_intent_scaffold,node_intent_runner,node_armed_contract,node_transport_rules,node_phrase_map toneTeal
```

## Components

### Repo overview

Top-level docs and snapshot tooling

- [README](https://github.com/crushn8r/gopod/blob/main/README.md): repo spec · Primary repository overview and live flow description · `README.md`
- [Goverlord README](https://github.com/crushn8r/gopod/blob/main/goverlord/README.md): architecture notes · Subsystem-level documentation for the goverlord tree · `goverlord/README.md`
- [goshot.sh](https://github.com/crushn8r/gopod/blob/main/goshot.sh): ops utility · Snapshot and state-capture helper · `goshot.sh`

### Input routing

Push-to-talk and keypad routing into the session

- [Input logic](https://github.com/crushn8r/gopod/blob/main/goverlord/gomads/low_level/input_gomad/input_event_logic.py): keypad router · Push-to-talk and keypad event routing logic · `goverlord/gomads/low_level/input_gomad/input_event_logic.py`
- [Input bridge](https://github.com/crushn8r/gopod/blob/main/goverlord/gomads/low_level/input_gomad/wiring/input_bridge.py): bridge · Wiring layer into input routing · `goverlord/gomads/low_level/input_gomad/wiring/input_bridge.py`
- [Input contract](https://github.com/crushn8r/gopod/blob/main/goverlord/gomads/low_level/input_gomad/contracts/input_contract.py): contract · Expected input behavior and interface contract · `goverlord/gomads/low_level/input_gomad/contracts/input_contract.py`

### Robot interface

Speech and expression translation for robot-safe output

- [Speech logic](https://github.com/crushn8r/gopod/blob/main/goverlord/gomads/low_level/robot_interface_gomad/robot_speech_logic.py): speech mapper · Robot-facing speech orchestration · `goverlord/gomads/low_level/robot_interface_gomad/robot_speech_logic.py`
- [Expr parser](https://github.com/crushn8r/gopod/blob/main/goverlord/gomads/low_level/robot_interface_gomad/code/robot_expression_parser_001.py): expression parser · Parses robot expression and marker signals · `goverlord/gomads/low_level/robot_interface_gomad/code/robot_expression_parser_001.py`
- [Robot bridge](https://github.com/crushn8r/gopod/blob/main/goverlord/gomads/low_level/robot_interface_gomad/wiring/robot_interface_bridge.py): bridge · Wiring layer into robot interface logic · `goverlord/gomads/low_level/robot_interface_gomad/wiring/robot_interface_bridge.py`
- [Robot contract](https://github.com/crushn8r/gopod/blob/main/goverlord/gomads/low_level/robot_interface_gomad/contracts/robot_interface_contract.py): contract · Robot interface expectations and boundary rules · `goverlord/gomads/low_level/robot_interface_gomad/contracts/robot_interface_contract.py`

### Robot safety

Outbound text guarding and replacement before robot speech

- [Safe guard](https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/robot/robot_io/robot_safe_packet_guard.py): text safety · Protects robot I/O from unsafe outbound packets · `goverlord/runtime/robot/robot_io/robot_safe_packet_guard.py`
- [Text filter](https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/robot/robot_io/outbound_text_filter_001.py): sanitizer · Outbound text filtering for robot-safe speech · `goverlord/runtime/robot/robot_io/outbound_text_filter_001.py`
- [Replacement filter](https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/robot/robot_io/text_replacement_filter.py): rewrite filter · Applies text substitutions before robot output · `goverlord/runtime/robot/robot_io/text_replacement_filter.py`
- [Rules](https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/prelaunch/replacement_rules_001.json): prelaunch config · Prelaunch text replacement rules · `goverlord/runtime/prelaunch/replacement_rules_001.json`

### Voice runtime

Verification and local TTS status support

- [Audio verifier](https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/voice/gopod_audio_execution_verifier_001.py): execution verifier · Checks local audio execution path · `goverlord/runtime/voice/gopod_audio_execution_verifier_001.py`
- [Proof ladder](https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/voice/audio_proof_ladder_001.py): verification ladder · Audio proof and verification staging · `goverlord/runtime/voice/audio_proof_ladder_001.py`
- [TTS announcer](https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/voice/local_tts_voice_registry_001/interview_status_kokoro_announcer_001.py): voice registry · Local TTS status and announcement support · `goverlord/runtime/voice/local_tts_voice_registry_001/interview_status_kokoro_announcer_001.py`

### Wire-Pod intent

Intent scaffold and contract boundary for GOPOD Yourself

- [GOPOD intent](https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/wire-pod/wirepod_intents/gopod_yourself_001/gopod_yourself_intent_001.json): Wire-Pod intent · Intent definition and handoff boundary into GOPOD Yourself · `goverlord/runtime/wire-pod/wirepod_intents/gopod_yourself_001/gopod_yourself_intent_001.json`
- [Dry run](https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/wire-pod/wirepod_intents/gopod_yourself_001/gopod_yourself_dry_run.py): intent runner · Executable path used by the intent scaffold · `goverlord/runtime/wire-pod/wirepod_intents/gopod_yourself_001/gopod_yourself_dry_run.py`
- [Armed mode](https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/wire-pod/wirepod_intents/gopod_yourself_001/gopod_armed_mode_contract_001.md): contract · Behavior-control and armed-mode contract · `goverlord/runtime/wire-pod/wirepod_intents/gopod_yourself_001/gopod_armed_mode_contract_001.md`
- [Transport rules](https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/wire-pod/wirepod_intents/gopod_yourself_001/do_not_invent_transport_rules_001.md): contract · Intent transport and execution constraints · `goverlord/runtime/wire-pod/wirepod_intents/gopod_yourself_001/do_not_invent_transport_rules_001.md`
- [Phrase map](https://github.com/crushn8r/gopod/blob/main/goverlord/runtime/wire-pod/wirepod_intents/gopod_yourself_001/operator_phrase_map_001.md): operator map · Operator phrases mapped to intent actions · `goverlord/runtime/wire-pod/wirepod_intents/gopod_yourself_001/operator_phrase_map_001.md`

### External runtime

Dependencies and control plane outside this repository

- **Wire-Pod**: external control plane · Robot server and intent router outside this repository
- **Ollama**: external model · Local LLM runtime used by the live session
- **Vosk**: external STT · Local speech-to-text runtime used by the live session

## Connections

- README → Wire-Pod: describes control plane · Repository overview frames Wire-Pod as the session entry and robot API boundary
- README → Input logic: documents ptt flow · Top-level README describes keypad and push-to-talk routing
- README → Safe guard: documents safety · Top-level README explains outbound robot text safety
- GOPOD intent → Dry run: executes · The intent scaffold hands off to the dry-run executable
- Wire-Pod → GOPOD intent: dispatches intent · Wire-Pod matches the wake phrase and launches the GOPOD intent path
- Armed mode → Dry run: constrains · Armed-mode rules shape allowed behavior in the runner
- Transport rules → Dry run: constrains · Transport rules define how the intent path may move data
- Phrase map → GOPOD intent: maps phrases · Operator phrase mappings feed the intent boundary
- Input bridge → Input logic: routes events · Bridge connects raw keypad events to routing logic
- Input contract → Input logic: defines contract · Input behavior is governed by the contract layer
- Input logic → Robot bridge: selects persona · Input routing chooses the downstream robot-facing persona path
- Robot bridge → Speech logic: invokes · Bridge hands session output to robot speech logic
- Robot contract → Speech logic: defines contract · Robot interface expectations constrain speech handling
- Expr parser → Speech logic: parses markers · Expression parsing supports robot-safe output formatting
- Speech logic → Safe guard: emits text · Robot speech output passes into the safety boundary
- Rules → Replacement filter: supplies rules · Prelaunch substitutions feed the replacement filter
- Safe guard → Text filter: filters · Safety guard invokes outbound text filtering
- Text filter → Replacement filter: rewrites · Outbound text is normalized through replacement rules
- Replacement filter → Wire-Pod: returns speech · Sanitized text is ready for robot-side delivery through Wire-Pod
- Proof ladder → Audio verifier: feeds checks · Verification ladder supports execution verification
- TTS announcer → Audio verifier: announces status · Voice registry status output is part of verification support
- Audio verifier → Vosk: verifies via · Live audio path depends on local speech recognition support
- Audio verifier → Ollama: verifies via · Live session verification assumes local model execution
- Goverlord README → Input bridge: documents subsystem · Goverlord documentation frames the low-level input subsystem
- Goverlord README → Robot bridge: documents subsystem · Goverlord documentation frames the robot interface subsystem
- Goverlord README → Safe guard: documents safety · Goverlord documentation frames robot I/O safety as a boundary
- Goverlord README → GOPOD intent: documents handoff · Goverlord documentation references the Wire-Pod intent boundary
