# og-cz/ivy architecture

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

- Interactive diagram: https://gitdiagram.com/og-cz/ivy
- Repository: https://github.com/og-cz/ivy

## Overview

#### Purpose and Entry Points
Ivy is a primarily local Python voice assistant: it accepts spoken interaction, optionally activates on “Hey, Ivy,” interprets commands or conversation, performs local/device/web-backed actions, and returns voice/UI feedback. Launch is documented through `run.py`; application orchestration likely begins across `run.py` and `main.py`. Shared runtime settings are centralized in `config.py`.

#### Interaction Runtime
The assistant’s control loop is organized around command intake, feature execution, and response delivery:
- `lib/main/command.py` is the command interpretation/dispatch extension point.
- `lib/main/features.py` implements assistant capabilities.
- `lib/main/response.py` produces user-facing replies.
- `lib/main/helper.py` supports the main execution path.

The browser-based companion UI is static HTML/CSS/JavaScript, rooted at `ui/index.html`, with runtime behavior in `ui/js/controller.js` and `ui/js/main.js`. It supplies visual state and bundled audio/animations rather than defining the backend.

#### Speech and Local ML Boundary
Bundled models make key voice features locally deployable:
- `model/hot-word-detection/hey-ivy_en_windows_v3_0_0.ppn` provides the Windows hotword model.
- `machine-learning/faster-whisper-small.en/model.bin` and its tokenizer/config files provide a local Faster Whisper speech-recognition model.
- `model/model.bin` with `model/tokenizer.json` is another packaged model artifact.

These model directories are an inference-resource boundary: application code consumes their files, while model binaries and vocabularies should be treated as versioned runtime assets.

#### Command, Conversation, and NLP Routing
Conversational handling is separated from action-oriented commands:
- `lib/conversations/router.py` selects a conversation path.
- `lib/conversations/ivy.py` holds assistant-specific dialogue behavior.
- `lib/conversations/casual.py`, `facts.py`, `fun.py`, and `history.py` provide distinct conversational domains/state.
- `lib/math/calculator.py` supplies deterministic natural-language/math calculation.

This separation allows input to resolve either to conversational output or command/feature execution, avoiding a cloud LLM dependency.

#### External Information and Device Integrations
Feature execution crosses into local system services and internet-enabled providers:
- `lib/utils/system_info.py` collects device status.
- `lib/utils/location.py` and `lib/utils/weather.py` support location/weather lookup.
- `lib/main/features.py` is the likely integration layer for web search, Wikipedia, news, YouTube, application launch, and communication features described by the project.

Internet access is therefore optional but required for dynamic information; offline behavior is supported by local speech/models, conversational logic, math, and system-oriented actions.

#### Persistence and Personalization
SQLite-backed application data resides in `database/ivy.db`, accessed through `database/db.py`. This is the persistence boundary for user preferences/configuration and database-backed command mappings such as websites or applications. `config.py` likely provides environment- or deployment-specific values used by database and external-service integrations.

#### Authentication Subsystem
Face authentication is an isolated computer-vision workflow:
- `lib/auth/sample.py` captures training samples.
- `lib/auth/trainer.py` builds the recognizer model.
- `lib/auth/recognize.py` performs recognition at runtime.
- `lib/auth/trainer/trainer.yml` stores trained recognizer output; `lib/auth/haarcascade_frontalface_default.xml` provides face detection data.

This subsystem gates or personalizes assistant access without requiring a remote identity service.

Main entry points: [`run.py`](https://github.com/og-cz/ivy/blob/main/run.py) (Launch & orchestration), [`lib/main/command.py`](https://github.com/og-cz/ivy/blob/main/lib/main/command.py) (Command dispatcher), [`lib/main/features.py`](https://github.com/og-cz/ivy/blob/main/lib/main/features.py) (Feature execution), [`config.py`](https://github.com/og-cz/ivy/blob/main/config.py) (Runtime settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Assistant Runtime"]
  node_launcher["Launch &amp; orchestration<br/>Python entrypoint<br/>[run.py]"]
  node_settings["Runtime settings<br/>Python config<br/>[config.py]"]
  node_command["Command dispatcher<br/>Python module<br/>[command.py]"]
  node_features["Feature execution<br/>Python module<br/>[features.py]"]
  node_response["Response delivery<br/>Python module<br/>[response.py]"]
  node_ui["Companion UI<br/>Static web UI<br/>[index.html]"]
  node_ui_controller["UI controller<br/>Browser JavaScript<br/>[controller.js]"]
end

subgraph group_conversation["Conversation &amp; NLP"]
  node_conversation_router["Conversation router<br/>Python module<br/>[router.py]"]
  node_ivy_dialogue["Ivy dialogue domains<br/>Python dialogue logic<br/>[ivy.py]"]
  node_calculator["Natural-language calculator<br/>Python module<br/>[calculator.py]"]
end

subgraph group_resources["Local Resources"]
  node_speech_models[("Local speech models<br/>Inference assets<br/>[model.bin]")]
  node_database_access["Persistence access<br/>Python database module<br/>[db.py]"]
  node_ivy_database[("Ivy SQLite data<br/>SQLite database<br/>[ivy.db]")]
end

subgraph group_integrations["External &amp; Device Services"]
  node_device_web{{"Device &amp; web providers<br/>Integration boundary<br/>[system_info.py]"}}
end

subgraph group_authentication["Face Authentication"]
  node_face_recognition["Face recognition<br/>Python CV runtime<br/>[recognize.py]"]
  node_face_training["Face enrollment &amp; training<br/>Python CV pipeline<br/>[trainer.py]"]
  node_face_model[("Trained face model<br/>CV model asset<br/>[trainer.yml]")]
end

node_launcher -->|"starts"| node_command
node_launcher -->|"loads"| node_settings
node_launcher -.->|"optionally gates access"| node_face_recognition
node_command -->|"routes conversation"| node_conversation_router
node_command -->|"routes actions"| node_features
node_command -->|"routes math"| node_calculator
node_conversation_router -->|"selects domain"| node_ivy_dialogue
node_conversation_router -->|"returns reply"| node_response
node_features -->|"returns result"| node_response
node_features -->|"reads mappings and preferences"| node_database_access
node_features -->|"uses"| node_device_web
node_database_access -->|"persists"| node_ivy_database
node_launcher -->|"uses local voice inference"| node_speech_models
node_response -.->|"updates visual feedback"| node_ui
node_ui -->|"loads"| node_ui_controller
node_face_training -->|"writes"| node_face_model
node_face_recognition -->|"loads"| node_face_model
node_settings -.->|"configures"| node_database_access
node_settings -.->|"configures providers"| node_device_web

click node_launcher "https://github.com/og-cz/ivy/blob/main/run.py"
click node_settings "https://github.com/og-cz/ivy/blob/main/config.py"
click node_command "https://github.com/og-cz/ivy/blob/main/lib/main/command.py"
click node_features "https://github.com/og-cz/ivy/blob/main/lib/main/features.py"
click node_response "https://github.com/og-cz/ivy/blob/main/lib/main/response.py"
click node_ui "https://github.com/og-cz/ivy/blob/main/ui/index.html"
click node_ui_controller "https://github.com/og-cz/ivy/blob/main/ui/js/controller.js"
click node_conversation_router "https://github.com/og-cz/ivy/blob/main/lib/conversations/router.py"
click node_ivy_dialogue "https://github.com/og-cz/ivy/blob/main/lib/conversations/ivy.py"
click node_calculator "https://github.com/og-cz/ivy/blob/main/lib/math/calculator.py"
click node_speech_models "https://github.com/og-cz/ivy/blob/main/machine-learning/faster-whisper-small.en/model.bin"
click node_database_access "https://github.com/og-cz/ivy/blob/main/database/db.py"
click node_ivy_database "https://github.com/og-cz/ivy/blob/main/database/ivy.db"
click node_device_web "https://github.com/og-cz/ivy/blob/main/lib/utils/system_info.py"
click node_face_recognition "https://github.com/og-cz/ivy/blob/main/lib/auth/recognize.py"
click node_face_training "https://github.com/og-cz/ivy/blob/main/lib/auth/trainer.py"
click node_face_model "https://github.com/og-cz/ivy/blob/main/lib/auth/trainer/trainer.yml"

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_launcher,node_settings,node_command,node_features,node_response,node_ui,node_ui_controller toneBlue
class node_conversation_router,node_ivy_dialogue,node_calculator toneAmber
class node_speech_models,node_database_access,node_ivy_database toneMint
class node_device_web toneRose
class node_face_recognition,node_face_training,node_face_model toneIndigo
```

## Components

### Assistant Runtime

- [Launch & orchestration](https://github.com/og-cz/ivy/blob/main/run.py): Python entrypoint · Starts the assistant runtime. · `run.py`
- [Runtime settings](https://github.com/og-cz/ivy/blob/main/config.py): Python config · `config.py`
- [Command dispatcher](https://github.com/og-cz/ivy/blob/main/lib/main/command.py): Python module · Interprets input and routes commands. · `lib/main/command.py`
- [Feature execution](https://github.com/og-cz/ivy/blob/main/lib/main/features.py): Python module · Runs assistant actions and provider integrations. · `lib/main/features.py`
- [Response delivery](https://github.com/og-cz/ivy/blob/main/lib/main/response.py): Python module · Produces user-facing replies. · `lib/main/response.py`
- [Companion UI](https://github.com/og-cz/ivy/blob/main/ui/index.html): Static web UI · Displays visual assistant state and bundled media. · `ui/index.html`
- [UI controller](https://github.com/og-cz/ivy/blob/main/ui/js/controller.js): Browser JavaScript · `ui/js/controller.js`

### Conversation & NLP

- [Conversation router](https://github.com/og-cz/ivy/blob/main/lib/conversations/router.py): Python module · Selects dialogue handling for conversational input. · `lib/conversations/router.py`
- [Ivy dialogue domains](https://github.com/og-cz/ivy/blob/main/lib/conversations/ivy.py): Python dialogue logic · Assistant dialogue, casual chat, facts, fun, and history. · `lib/conversations/ivy.py`
- [Natural-language calculator](https://github.com/og-cz/ivy/blob/main/lib/math/calculator.py): Python module · `lib/math/calculator.py`

### Local Resources

- [Local speech models](https://github.com/og-cz/ivy/blob/main/machine-learning/faster-whisper-small.en/model.bin): Inference assets · Hotword and Faster Whisper recognition assets. · `machine-learning/faster-whisper-small.en/model.bin`
- [Persistence access](https://github.com/og-cz/ivy/blob/main/database/db.py): Python database module · `database/db.py`
- [Ivy SQLite data](https://github.com/og-cz/ivy/blob/main/database/ivy.db): SQLite database · Preferences and command mappings. · `database/ivy.db`

### External & Device Services

- [Device & web providers](https://github.com/og-cz/ivy/blob/main/lib/utils/system_info.py): Integration boundary · System status, location, weather, search, and online content. · `lib/utils/system_info.py`

### Face Authentication

- [Face recognition](https://github.com/og-cz/ivy/blob/main/lib/auth/recognize.py): Python CV runtime · Recognizes users locally at runtime. · `lib/auth/recognize.py`
- [Face enrollment & training](https://github.com/og-cz/ivy/blob/main/lib/auth/trainer.py): Python CV pipeline · Captures samples and trains the recognizer. · `lib/auth/trainer.py`
- [Trained face model](https://github.com/og-cz/ivy/blob/main/lib/auth/trainer/trainer.yml): CV model asset · `lib/auth/trainer/trainer.yml`

## Connections

- Launch & orchestration → Command dispatcher: starts
- Launch & orchestration → Runtime settings: loads
- Launch & orchestration → Face recognition: optionally gates access
- Command dispatcher → Conversation router: routes conversation
- Command dispatcher → Feature execution: routes actions
- Command dispatcher → Natural-language calculator: routes math
- Conversation router → Ivy dialogue domains: selects domain
- Conversation router → Response delivery: returns reply
- Feature execution → Response delivery: returns result
- Feature execution → Persistence access: reads mappings and preferences
- Feature execution → Device & web providers: uses
- Persistence access → Ivy SQLite data: persists
- Launch & orchestration → Local speech models: uses local voice inference
- Response delivery → Companion UI: updates visual feedback
- Companion UI → UI controller: loads
- Face enrollment & training → Trained face model: writes
- Face recognition → Trained face model: loads
- Runtime settings → Persistence access: configures
- Runtime settings → Device & web providers: configures providers