# arkybruh7/kara architecture

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

- Interactive diagram: https://gitdiagram.com/arkybruh7/kara
- Repository: https://github.com/arkybruh7/kara

## Overview

Kara is a local, terminal-based AI companion: a user enters a message, the Node.js app builds a personality-aware prompt and sends it to local Ollama/Qwen, then prints the reply. For playlist requests, Ollama can dispatch a tool that looks up a configured playlist and launches a Python desktop-automation script to open Spotify and find its play button. The repository also contains a separate speech-to-text typing utility. Main chat and Spotify wiring are supported by sampled source; the voice utility is shown as a standalone capability.

Main entry points: [`app.js`](https://github.com/arkybruh7/kara/blob/main/app.js) (Chat and orchestration), [`apps/tools.js`](https://github.com/arkybruh7/kara/blob/main/apps/tools.js) (Tool dispatch), [`services/voice_typing.py`](https://github.com/arkybruh7/kara/blob/main/services/voice_typing.py) (Speech typing), [`apps/openApp.py`](https://github.com/arkybruh7/kara/blob/main/apps/openApp.py) (Spotify launcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Conversation"]
  node_app["Chat and orchestration<br/>[app.js]"]
  node_personality["Kara personality<br/>[kara.json]"]
  node_ollama["Ollama Qwen"]
end

subgraph group_playlist["Playlist playback"]
  node_tools["Tool dispatch<br/>[tools.js]"]
  node_playlist_data["Playlist registry<br/>[spotify.json]"]
  node_launcher["Spotify launcher<br/>[openApp.py]"]
  node_spotify["Spotify desktop app"]
end

subgraph group_voice["Voice typing"]
  node_voice["Speech typing<br/>[voice_typing.py]"]
end

node_user(("Terminal user"))
node_microphone(("Microphone input"))
node_speech_api["Google speech recognition"]
node_keyboard["System keyboard"]

node_user -->|"enters prompts"| node_app
node_app -->|"loads traits"| node_personality
node_app -->|"sends chat"| node_ollama
node_ollama -->|"returns reply or tool call"| node_app
node_app -->|"dispatches tool"| node_tools
node_tools -->|"reads playlists"| node_playlist_data
node_tools -->|"launches script"| node_launcher
node_launcher -->|"opens playlist and clicks play"| node_spotify
node_app -->|"prints response"| node_user
node_microphone -->|"provides audio"| node_voice
node_voice -->|"transcribes audio"| node_speech_api
node_voice -->|"types recognized text"| node_keyboard

click node_app "https://github.com/arkybruh7/kara/blob/main/app.js"
click node_personality "https://github.com/arkybruh7/kara/blob/main/personality/kara.json"
click node_tools "https://github.com/arkybruh7/kara/blob/main/apps/tools.js"
click node_playlist_data "https://github.com/arkybruh7/kara/blob/main/apps/spotify.json"
click node_launcher "https://github.com/arkybruh7/kara/blob/main/apps/openApp.py"
click node_voice "https://github.com/arkybruh7/kara/blob/main/services/voice_typing.py"

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_personality,node_ollama,node_user toneBlue
class node_tools,node_playlist_data,node_launcher,node_spotify toneAmber
class node_voice toneMint
class node_microphone,node_speech_api,node_keyboard toneIndigo
```

## Components

### Conversation

- [Chat and orchestration](https://github.com/arkybruh7/kara/blob/main/app.js): `app.js`
- [Kara personality](https://github.com/arkybruh7/kara/blob/main/personality/kara.json): `personality/kara.json`
- **Ollama Qwen**

### Playlist playback

- [Tool dispatch](https://github.com/arkybruh7/kara/blob/main/apps/tools.js): `apps/tools.js`
- [Playlist registry](https://github.com/arkybruh7/kara/blob/main/apps/spotify.json): `apps/spotify.json`
- [Spotify launcher](https://github.com/arkybruh7/kara/blob/main/apps/openApp.py): `apps/openApp.py`
- **Spotify desktop app**

### Voice typing

- [Speech typing](https://github.com/arkybruh7/kara/blob/main/services/voice_typing.py): `services/voice_typing.py`

### Other components

- **Terminal user**
- **Microphone input**
- **Google speech recognition**
- **System keyboard**

## Connections

- Terminal user → Chat and orchestration: enters prompts
- Chat and orchestration → Kara personality: loads traits
- Chat and orchestration → Ollama Qwen: sends chat
- Ollama Qwen → Chat and orchestration: returns reply or tool call
- Chat and orchestration → Tool dispatch: dispatches tool
- Tool dispatch → Playlist registry: reads playlists
- Tool dispatch → Spotify launcher: launches script
- Spotify launcher → Spotify desktop app: opens playlist and clicks play
- Chat and orchestration → Terminal user: prints response
- Microphone input → Speech typing: provides audio
- Speech typing → Google speech recognition: transcribes audio
- Speech typing → System keyboard: types recognized text