# musubipapi/computah architecture

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

- Interactive diagram: https://gitdiagram.com/musubipapi/computah
- Repository: https://github.com/musubipapi/computah

## Overview

Computah is a macOS voice-controlled app that turns speech (or debug-typed commands) into checked actions in the frontmost app. Its documented flow runs from turn capture through accessibility observation, Jev choice, guarded native input, and post-action verification, with checkpoints and bounded recovery. The graph preserves UI, diagnostics, and model-cost capabilities. Several internal implementations are unsampled; those branches use documented behavior or indexed references, and uncertain wiring is omitted.

Main entry points: [`Sources/ComputahCore/Commands/CommandEngine.swift`](https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Commands/CommandEngine.swift) (Command engine), [`Sources/Computah/App.swift`](https://github.com/musubipapi/computah/blob/main/Sources/Computah/App.swift) (App coordinator), [`Sources/Computah/Voice.swift`](https://github.com/musubipapi/computah/blob/main/Sources/Computah/Voice.swift) (Voice session), [`Sources/ComputahCore/Commands/CommandCoordinator.swift`](https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Commands/CommandCoordinator.swift) (Command coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Mac app"]
  node_app["App coordinator<br/>[App.swift]"]
  node_notch["Notch panel<br/>[NotchPanel.swift]"]
  node_debug["Debug panel<br/>[DebugPanel.swift]"]
  node_runhistory[("Run history<br/>[RunHistory.swift]")]
  node_coststore[("Jev cost store<br/>[JevCostStore.swift]")]
  node_diagnostics["Diagnostic output"]
end

subgraph group_input["Speech input"]
  node_voice["Voice session<br/>[Voice.swift]"]
  node_turnid["Turn identity"]
end

subgraph group_observe["Accessibility"]
  node_reader["AX reader<br/>[AXReader.swift]"]
  node_grouping["Control grouping<br/>[AXGrouping.swift]"]
  node_actor["Native actions<br/>[AXActor.swift]"]
  node_routing["App routing<br/>[AppRouting.swift]"]
end

subgraph group_control["Command execution"]
  node_coordinator["Command coordinator"]
  node_engine["Command engine"]
  node_workflow["Task workflow<br/>[Workflow.swift]"]
  node_checkpoint[("Task checkpoint")]
  node_recovery["Bounded recovery<br/>[Recovery.swift]"]
  node_verification["Result evidence"]
end

subgraph group_language["Jev language"]
  node_language["Command language"]
  node_choice["Jev selector<br/>[JevChoice.swift]"]
  node_sensitive["Sensitive text"]
end

node_user(("User"))
node_deepgram{{"Deepgram Flux"}}
node_typesafe{{"TypeSafe Jev"}}
node_targetapp["Frontmost app"]

node_user -->|"toggles listening"| node_notch
node_user -->|"types command"| node_debug
node_notch -->|"controls"| node_app
node_debug -->|"submits command"| node_app
node_app -->|"starts session"| node_voice
node_voice -.->|"streams audio"| node_deepgram
node_deepgram -.->|"returns turns"| node_voice
node_voice -.->|"identifies turns"| node_turnid
node_voice -->|"submits final turn"| node_coordinator
node_app -->|"submits command"| node_coordinator
node_coordinator -->|"prepares action"| node_engine
node_coordinator -.->|"runs task"| node_workflow
node_coordinator -->|"retains progress"| node_checkpoint
node_workflow -->|"records progress"| node_checkpoint
node_engine -->|"reads controls"| node_reader
node_engine -->|"finds apps"| node_routing
node_reader -.->|"observes controls"| node_targetapp
node_reader -->|"provides snapshot"| node_grouping
node_engine -->|"groups choices"| node_grouping
node_engine -->|"interprets command"| node_language
node_language -.->|"asks selector"| node_choice
node_choice -.->|"sends judgments"| node_typesafe
node_typesafe -.->|"returns decisions"| node_choice
node_language -->|"protects text"| node_sensitive
node_engine -->|"performs checked action"| node_actor
node_actor -.->|"sends input"| node_targetapp
node_engine -->|"requests reread"| node_recovery
node_workflow -->|"checks outcome"| node_verification
node_verification -.->|"checks observed state"| node_reader
node_app -->|"records results"| node_runhistory
node_debug -.->|"shows cost total"| node_coststore
node_app -.->|"emits diagnostics"| node_diagnostics
node_runhistory -->|"supplies review"| node_debug

click node_app "https://github.com/musubipapi/computah/blob/main/Sources/Computah/App.swift"
click node_notch "https://github.com/musubipapi/computah/blob/main/Sources/Computah/UI/NotchPanel.swift"
click node_debug "https://github.com/musubipapi/computah/blob/main/Sources/Computah/UI/DebugPanel.swift"
click node_runhistory "https://github.com/musubipapi/computah/blob/main/Sources/Computah/Diagnostics/RunHistory.swift"
click node_coststore "https://github.com/musubipapi/computah/blob/main/Sources/Computah/Diagnostics/JevCostStore.swift"
click node_voice "https://github.com/musubipapi/computah/blob/main/Sources/Computah/Voice.swift"
click node_turnid "https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Language/SpeechTurnIdentity.swift"
click node_reader "https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Accessibility/AXReader.swift"
click node_grouping "https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Accessibility/AXGrouping.swift"
click node_actor "https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Accessibility/AXActor.swift"
click node_routing "https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/AppRouting.swift"
click node_coordinator "https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Commands/CommandCoordinator.swift"
click node_engine "https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Commands/CommandEngine.swift"
click node_workflow "https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Commands/Workflow.swift"
click node_checkpoint "https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Commands/WorkflowCheckpoint.swift"
click node_recovery "https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Commands/Recovery.swift"
click node_verification "https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Commands/VerificationEvidence.swift"
click node_language "https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Language/CommandLanguage.swift"
click node_choice "https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Language/JevChoice.swift"
click node_sensitive "https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Diagnostics/SensitiveText.swift"
click node_diagnostics "https://github.com/musubipapi/computah/blob/main/Sources/Computah/Diagnostics/DiagnosticOutput.swift"

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_app,node_notch,node_debug,node_runhistory,node_coststore,node_diagnostics,node_user toneBlue
class node_voice,node_turnid toneAmber
class node_reader,node_grouping,node_actor,node_routing toneMint
class node_coordinator,node_engine,node_workflow,node_checkpoint,node_recovery,node_verification toneRose
class node_language,node_choice,node_sensitive,node_deepgram,node_typesafe,node_targetapp toneIndigo
```

## Components

### Mac app

- [App coordinator](https://github.com/musubipapi/computah/blob/main/Sources/Computah/App.swift): `Sources/Computah/App.swift`
- [Notch panel](https://github.com/musubipapi/computah/blob/main/Sources/Computah/UI/NotchPanel.swift): `Sources/Computah/UI/NotchPanel.swift`
- [Debug panel](https://github.com/musubipapi/computah/blob/main/Sources/Computah/UI/DebugPanel.swift): `Sources/Computah/UI/DebugPanel.swift`
- [Run history](https://github.com/musubipapi/computah/blob/main/Sources/Computah/Diagnostics/RunHistory.swift): `Sources/Computah/Diagnostics/RunHistory.swift`
- [Jev cost store](https://github.com/musubipapi/computah/blob/main/Sources/Computah/Diagnostics/JevCostStore.swift): `Sources/Computah/Diagnostics/JevCostStore.swift`
- [Diagnostic output](https://github.com/musubipapi/computah/blob/main/Sources/Computah/Diagnostics/DiagnosticOutput.swift): `Sources/Computah/Diagnostics/DiagnosticOutput.swift`

### Speech input

- [Voice session](https://github.com/musubipapi/computah/blob/main/Sources/Computah/Voice.swift): `Sources/Computah/Voice.swift`
- [Turn identity](https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Language/SpeechTurnIdentity.swift): `Sources/ComputahCore/Language/SpeechTurnIdentity.swift`

### Accessibility

- [AX reader](https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Accessibility/AXReader.swift): `Sources/ComputahCore/Accessibility/AXReader.swift`
- [Control grouping](https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Accessibility/AXGrouping.swift): `Sources/ComputahCore/Accessibility/AXGrouping.swift`
- [Native actions](https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Accessibility/AXActor.swift): `Sources/ComputahCore/Accessibility/AXActor.swift`
- [App routing](https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/AppRouting.swift): `Sources/ComputahCore/AppRouting.swift`

### Command execution

- [Command coordinator](https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Commands/CommandCoordinator.swift): `Sources/ComputahCore/Commands/CommandCoordinator.swift`
- [Command engine](https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Commands/CommandEngine.swift): `Sources/ComputahCore/Commands/CommandEngine.swift`
- [Task workflow](https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Commands/Workflow.swift): `Sources/ComputahCore/Commands/Workflow.swift`
- [Task checkpoint](https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Commands/WorkflowCheckpoint.swift): `Sources/ComputahCore/Commands/WorkflowCheckpoint.swift`
- [Bounded recovery](https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Commands/Recovery.swift): `Sources/ComputahCore/Commands/Recovery.swift`
- [Result evidence](https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Commands/VerificationEvidence.swift): `Sources/ComputahCore/Commands/VerificationEvidence.swift`

### Jev language

- [Command language](https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Language/CommandLanguage.swift): `Sources/ComputahCore/Language/CommandLanguage.swift`
- [Jev selector](https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Language/JevChoice.swift): `Sources/ComputahCore/Language/JevChoice.swift`
- [Sensitive text](https://github.com/musubipapi/computah/blob/main/Sources/ComputahCore/Diagnostics/SensitiveText.swift): `Sources/ComputahCore/Diagnostics/SensitiveText.swift`

### Other components

- **User**
- **Deepgram Flux**
- **TypeSafe Jev**
- **Frontmost app**

## Connections

- User → Notch panel: toggles listening
- User → Debug panel: types command (evidence: `Sources/Computah/UI/DebugPanel.swift`)
- Notch panel → App coordinator: controls (evidence: `Sources/Computah/App.swift`)
- Debug panel → App coordinator: submits command (evidence: `Sources/Computah/App.swift`)
- App coordinator → Voice session: starts session (evidence: `Sources/Computah/App.swift`)
- Voice session → Deepgram Flux: streams audio (evidence: `README.md`)
- Deepgram Flux → Voice session: returns turns (evidence: `README.md`)
- Voice session → Turn identity: identifies turns (evidence: `README.md`)
- Voice session → Command coordinator: submits final turn (evidence: `Sources/Computah/App.swift`)
- App coordinator → Command coordinator: submits command (evidence: `Sources/Computah/App.swift`)
- Command coordinator → Command engine: prepares action (evidence: `Sources/ComputahCore/Commands/CommandCoordinator.swift`)
- Command coordinator → Task workflow: runs task (evidence: `Sources/ComputahCore/Commands/Workflow.swift`)
- Command coordinator → Task checkpoint: retains progress (evidence: `Sources/ComputahCore/Commands/CommandCoordinator.swift`)
- Task workflow → Task checkpoint: records progress (evidence: `Sources/ComputahCore/Commands/Workflow.swift`)
- Command engine → AX reader: reads controls (evidence: `Sources/ComputahCore/Commands/CommandEngine.swift`)
- Command engine → App routing: finds apps (evidence: `Sources/ComputahCore/Commands/CommandEngine.swift`)
- AX reader → Frontmost app: observes controls (evidence: `README.md`)
- AX reader → Control grouping: provides snapshot (evidence: `Sources/ComputahCore/Accessibility/AXReader.swift`)
- Command engine → Control grouping: groups choices (evidence: `Sources/ComputahCore/Commands/CommandEngine.swift`)
- Command engine → Command language: interprets command (evidence: `Sources/ComputahCore/Commands/CommandEngine.swift`)
- Command language → Jev selector: asks selector (evidence: `Sources/ComputahCore/Language/CommandLanguage.swift`)
- Jev selector → TypeSafe Jev: sends judgments (evidence: `README.md`)
- TypeSafe Jev → Jev selector: returns decisions (evidence: `README.md`)
- Command language → Sensitive text: protects text (evidence: `Sources/ComputahCore/Language/CommandLanguage.swift`)
- Command engine → Native actions: performs checked action (evidence: `Sources/ComputahCore/Commands/CommandEngine.swift`)
- Native actions → Frontmost app: sends input (evidence: `README.md`)
- Command engine → Bounded recovery: requests reread (evidence: `Sources/ComputahCore/Commands/CommandEngine.swift`)
- Task workflow → Result evidence: checks outcome (evidence: `Sources/ComputahCore/Commands/Workflow.swift`)
- Result evidence → AX reader: checks observed state (evidence: `README.md`)
- App coordinator → Run history: records results (evidence: `Sources/Computah/App.swift`)
- Debug panel → Jev cost store: shows cost total (evidence: `Sources/Computah/UI/DebugPanel.swift`)
- App coordinator → Diagnostic output: emits diagnostics (evidence: `Sources/Computah/Diagnostics/DiagnosticOutput.swift`)
- Run history → Debug panel: supplies review (evidence: `Sources/Computah/Diagnostics/RunHistory.swift`)
