# kenkaiii/roamies architecture

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

- Interactive diagram: https://gitdiagram.com/kenkaiii/roamies
- Repository: https://github.com/kenkaiii/roamies

## Overview

Roamies is a desktop AI companion: the user speaks or types, the agent handles requests and scheduled work, and replies appear as speech and on-screen drawings or computer actions. The graph includes the documented memory, skills, connections, and setup capabilities. Some subsystem links are based on README descriptions; unsampled modules are represented only where their paths are present in the tree, and uncertain wiring is omitted.

Main entry points: [`showcase/tauri/sidecar/sidekick.mjs`](https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/sidekick.mjs) (Agent runtime), [`showcase/tauri/sidecar/speaker.mjs`](https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/speaker.mjs) (Voice synthesis), [`showcase/tauri/src-tauri/src/main.rs`](https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/src-tauri/src/main.rs) (Desktop shell), [`showcase/tauri/sidecar/tools.mjs`](https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/tools.mjs) (Agent tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_shell["Desktop shell<br/>[main.rs]"]
  node_companion["Roamie UI"]
  node_panel["Settings panel<br/>[panel.js]"]
  node_setup["Onboarding<br/>[onboarding.js]"]
end

subgraph group_agent["Agent and memory"]
  node_sidecar["Agent runtime<br/>[sidekick.mjs]"]
  node_routing["Model routing<br/>[route.mjs]"]
  node_agenttools["Agent tools<br/>[tools.mjs]"]
  node_memory[("Memory store<br/>[store.mjs]")]
  node_schedules["Scheduled jobs<br/>[jobs.mjs]"]
  node_skills["Skills<br/>[skills.mjs]"]
  node_connections["MCP connections<br/>[local.mjs]"]
end

subgraph group_interaction["Voice and replies"]
  node_speechinput["Speech capture<br/>[speech.mjs]"]
  node_voices["Voice synthesis<br/>[speaker.mjs]"]
  node_fish["Fish Audio<br/>[fish.mjs]"]
  node_gemini["Gemini voice<br/>[gemini.mjs]"]
end

subgraph group_screen["Screen actions"]
  node_draw["Screen drawings<br/>[draw.mjs]"]
  node_hands["Computer control<br/>[main.rs]"]
end

subgraph group_native["Native platform"]
  node_linux["Linux desktop<br/>[linux.rs]"]
  node_tap["Input handling<br/>[tap.rs]"]
end

node_user(("User"))

node_user -->|"speaks or types"| node_companion
node_user -->|"opens settings"| node_panel
node_user -->|"sets up"| node_setup
node_companion -.->|"sends requests"| node_sidecar
node_sidecar -->|"selects model"| node_routing
node_routing -->|"routes turn"| node_sidecar
node_sidecar -->|"loads and saves"| node_memory
node_sidecar -.->|"runs scheduled work"| node_schedules
node_sidecar -.->|"uses skills"| node_skills
node_sidecar -->|"syncs servers"| node_connections
node_sidecar -.->|"invokes tools"| node_agenttools
node_user -->|"holds talk chord"| node_speechinput
node_speechinput -.->|"transcribes request"| node_sidecar
node_sidecar -->|"speaks reply"| node_voices
node_voices -->|"uses provider"| node_fish
node_voices -->|"uses provider"| node_gemini
node_voices -->|"uses speech services"| node_speechinput
node_agenttools -->|"checks drawing actions"| node_draw
node_agenttools -.->|"controls other apps"| node_hands
node_sidecar -.->|"communicates with"| node_shell
node_shell -->|"uses platform support"| node_linux
node_shell -->|"uses input handling"| node_tap

click node_shell "https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/src-tauri/src/main.rs"
click node_companion "https://github.com/kenkaiii/roamies/tree/main/showcase/roamies"
click node_panel "https://github.com/kenkaiii/roamies/blob/main/showcase/panel/panel.js"
click node_setup "https://github.com/kenkaiii/roamies/blob/main/showcase/onboarding/onboarding.js"
click node_sidecar "https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/sidekick.mjs"
click node_routing "https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/route.mjs"
click node_agenttools "https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/tools.mjs"
click node_memory "https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/store.mjs"
click node_schedules "https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/jobs.mjs"
click node_skills "https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/skills.mjs"
click node_connections "https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/local.mjs"
click node_speechinput "https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/speech.mjs"
click node_voices "https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/speaker.mjs"
click node_fish "https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/fish.mjs"
click node_gemini "https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/gemini.mjs"
click node_draw "https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/draw.mjs"
click node_hands "https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/src-tauri/hands-win/src/main.rs"
click node_linux "https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/src-tauri/src/linux.rs"
click node_tap "https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/src-tauri/src/tap.rs"

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_shell,node_companion,node_panel,node_setup,node_user toneBlue
class node_sidecar,node_routing,node_agenttools,node_memory,node_schedules,node_skills,node_connections toneAmber
class node_speechinput,node_voices,node_fish,node_gemini toneMint
class node_draw,node_hands toneRose
class node_linux,node_tap toneIndigo
```

## Components

### Desktop experience

- [Desktop shell](https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/src-tauri/src/main.rs): `showcase/tauri/src-tauri/src/main.rs`
- [Roamie UI](https://github.com/kenkaiii/roamies/tree/main/showcase/roamies): `showcase/roamies`
- [Settings panel](https://github.com/kenkaiii/roamies/blob/main/showcase/panel/panel.js): `showcase/panel/panel.js`
- [Onboarding](https://github.com/kenkaiii/roamies/blob/main/showcase/onboarding/onboarding.js): `showcase/onboarding/onboarding.js`

### Agent and memory

- [Agent runtime](https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/sidekick.mjs): `showcase/tauri/sidecar/sidekick.mjs`
- [Model routing](https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/route.mjs): `showcase/tauri/sidecar/route.mjs`
- [Agent tools](https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/tools.mjs): `showcase/tauri/sidecar/tools.mjs`
- [Memory store](https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/store.mjs): `showcase/tauri/sidecar/store.mjs`
- [Scheduled jobs](https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/jobs.mjs): `showcase/tauri/sidecar/jobs.mjs`
- [Skills](https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/skills.mjs): `showcase/tauri/sidecar/skills.mjs`
- [MCP connections](https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/local.mjs): `showcase/tauri/sidecar/local.mjs`

### Voice and replies

- [Speech capture](https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/speech.mjs): `showcase/tauri/sidecar/speech.mjs`
- [Voice synthesis](https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/speaker.mjs): `showcase/tauri/sidecar/speaker.mjs`
- [Fish Audio](https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/fish.mjs): `showcase/tauri/sidecar/fish.mjs`
- [Gemini voice](https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/gemini.mjs): `showcase/tauri/sidecar/gemini.mjs`

### Screen actions

- [Screen drawings](https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/sidecar/draw.mjs): `showcase/tauri/sidecar/draw.mjs`
- [Computer control](https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/src-tauri/hands-win/src/main.rs): `showcase/tauri/src-tauri/hands-win/src/main.rs`

### Native platform

- [Linux desktop](https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/src-tauri/src/linux.rs): `showcase/tauri/src-tauri/src/linux.rs`
- [Input handling](https://github.com/kenkaiii/roamies/blob/main/showcase/tauri/src-tauri/src/tap.rs): `showcase/tauri/src-tauri/src/tap.rs`

### Other components

- **User**

## Connections

- User → Roamie UI: speaks or types
- User → Settings panel: opens settings
- User → Onboarding: sets up
- Roamie UI → Agent runtime: sends requests
- Agent runtime → Model routing: selects model (evidence: `showcase/tauri/sidecar/route.mjs`)
- Model routing → Agent runtime: routes turn (evidence: `showcase/tauri/sidecar/route.mjs`)
- Agent runtime → Memory store: loads and saves (evidence: `showcase/tauri/sidecar/sidekick.mjs`)
- Agent runtime → Scheduled jobs: runs scheduled work
- Agent runtime → Skills: uses skills
- Agent runtime → MCP connections: syncs servers (evidence: `showcase/tauri/sidecar/sidekick.mjs`)
- Agent runtime → Agent tools: invokes tools (evidence: `showcase/tauri/sidecar/sidekick.mjs`)
- User → Speech capture: holds talk chord
- Speech capture → Agent runtime: transcribes request (evidence: `showcase/tauri/sidecar/sidekick.mjs`)
- Agent runtime → Voice synthesis: speaks reply (evidence: `showcase/tauri/sidecar/speaker.mjs`)
- Voice synthesis → Fish Audio: uses provider (evidence: `showcase/tauri/sidecar/speaker.mjs`)
- Voice synthesis → Gemini voice: uses provider (evidence: `showcase/tauri/sidecar/speaker.mjs`)
- Voice synthesis → Speech capture: uses speech services (evidence: `showcase/tauri/sidecar/speaker.mjs`)
- Agent tools → Screen drawings: checks drawing actions (evidence: `showcase/tauri/sidecar/tools.mjs`)
- Agent tools → Computer control: controls other apps
- Agent runtime → Desktop shell: communicates with
- Desktop shell → Linux desktop: uses platform support (evidence: `showcase/tauri/src-tauri/src/main.rs`)
- Desktop shell → Input handling: uses input handling (evidence: `showcase/tauri/src-tauri/src/main.rs`)
