# felsyn/felhaven architecture

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

- Interactive diagram: https://gitdiagram.com/felsyn/felhaven
- Repository: https://github.com/felsyn/felhaven

## Overview

Felhaven is a local-first Tk personal dashboard built from independent toolbox modules. The main workflow is a user question in the home chat, routed through Pythia to the local LLM and—when requested—tool handlers, then displayed and optionally narrated by Calliope. Kairos separately polls dashboard data workers and updates panels. The graph also preserves the README’s major view capabilities. Sampled excerpts are partial, so unsampled subsystem wiring is shown only where the README documents it.

Main entry points: [`metis_toolbox/tools`](https://github.com/felsyn/felhaven/tree/main/metis_toolbox/tools) (Tool handlers), [`metis_toolbox/panels`](https://github.com/felsyn/felhaven/tree/main/metis_toolbox/panels) (Dashboard views), [`metis_toolbox/pythia.py`](https://github.com/felsyn/felhaven/blob/main/metis_toolbox/pythia.py) (Pythia), [`metis_toolbox/panels/home_panel.py`](https://github.com/felsyn/felhaven/blob/main/metis_toolbox/panels/home_panel.py) (Home chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Dashboard interface"]
  node_felhaven["Felhaven app<br/>[felhaven.py]"]
  node_home["Home chat<br/>[home_panel.py]"]
  node_views["Dashboard views"]
end

subgraph group_coordination["Shared infrastructure"]
  node_harmonia["Audio output<br/>[harmonia.py]"]
  node_kairos["Kairos workers<br/>[kairos.py]"]
  node_cerberus["Secrets gate<br/>[cerberus.py]"]
end

subgraph group_assistant["Assistant workflow"]
  node_pythia["Pythia<br/>[pythia.py]"]
  node_toolhandlers["Tool handlers"]
  node_calliope["Calliope narration<br/>[calliope.py]"]
end

subgraph group_capabilities["Tool capabilities"]
  node_weather["Weather<br/>[aura.py]"]
  node_celestial["Sky and seasons"]
  node_cartography["Local chart<br/>[artemis.py]"]
  node_markets["Markets ledger<br/>[midas.py]"]
  node_news["RSS news<br/>[pheme.py]"]
  node_audio["YouTube audio<br/>[morpheus.py]"]
  node_utilities["Tasks and utilities"]
  node_archive["Markdown archive<br/>[herodotus.py]"]
  node_search["Web search<br/>[callimachus.py]"]
end

node_user(("User"))
node_ollama["Ollama LLM"]

node_user -->|"asks"| node_home
node_user -->|"selects view"| node_views
node_felhaven -->|"renders"| node_views
node_home -->|"asks"| node_pythia
node_pythia -->|"sends chat"| node_ollama
node_ollama -->|"returns reply"| node_pythia
node_pythia -->|"dispatches calls"| node_toolhandlers
node_toolhandlers -->|"handles"| node_weather
node_toolhandlers -->|"handles"| node_celestial
node_toolhandlers -->|"handles"| node_cartography
node_toolhandlers -->|"handles"| node_markets
node_toolhandlers -->|"handles"| node_news
node_toolhandlers -->|"handles"| node_audio
node_toolhandlers -->|"handles"| node_utilities
node_toolhandlers -->|"handles"| node_archive
node_toolhandlers -->|"handles"| node_search
node_home -->|"requests speech"| node_calliope
node_calliope -->|"sends PCM"| node_harmonia
node_kairos -->|"polls fetch"| node_toolhandlers
node_kairos -->|"updates panels"| node_views
node_views -->|"gates secrets"| node_cerberus
node_views -->|"shows holdings"| node_markets

click node_felhaven "https://github.com/felsyn/felhaven/blob/main/metis_toolbox/felhaven.py"
click node_home "https://github.com/felsyn/felhaven/blob/main/metis_toolbox/panels/home_panel.py"
click node_views "https://github.com/felsyn/felhaven/tree/main/metis_toolbox/panels"
click node_pythia "https://github.com/felsyn/felhaven/blob/main/metis_toolbox/pythia.py"
click node_toolhandlers "https://github.com/felsyn/felhaven/tree/main/metis_toolbox/tools"
click node_calliope "https://github.com/felsyn/felhaven/blob/main/metis_toolbox/calliope.py"
click node_harmonia "https://github.com/felsyn/felhaven/blob/main/metis_toolbox/harmonia.py"
click node_kairos "https://github.com/felsyn/felhaven/blob/main/metis_toolbox/kairos.py"
click node_cerberus "https://github.com/felsyn/felhaven/blob/main/metis_toolbox/cerberus.py"
click node_weather "https://github.com/felsyn/felhaven/blob/main/metis_toolbox/tools/aura.py"
click node_celestial "https://github.com/felsyn/felhaven/tree/main/metis_toolbox/tools"
click node_cartography "https://github.com/felsyn/felhaven/blob/main/metis_toolbox/tools/artemis.py"
click node_markets "https://github.com/felsyn/felhaven/blob/main/metis_toolbox/tools/midas.py"
click node_news "https://github.com/felsyn/felhaven/blob/main/metis_toolbox/tools/pheme.py"
click node_audio "https://github.com/felsyn/felhaven/blob/main/metis_toolbox/tools/morpheus.py"
click node_utilities "https://github.com/felsyn/felhaven/tree/main/metis_toolbox/tools"
click node_archive "https://github.com/felsyn/felhaven/blob/main/metis_toolbox/tools/herodotus.py"
click node_search "https://github.com/felsyn/felhaven/blob/main/metis_toolbox/tools/callimachus.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_felhaven,node_home,node_views,node_user toneBlue
class node_harmonia,node_kairos,node_cerberus toneAmber
class node_pythia,node_toolhandlers,node_calliope toneMint
class node_weather,node_celestial,node_cartography,node_markets,node_news,node_audio,node_utilities,node_archive,node_search toneRose
class node_ollama toneIndigo
```

## Components

### Dashboard interface

- [Felhaven app](https://github.com/felsyn/felhaven/blob/main/metis_toolbox/felhaven.py): `metis_toolbox/felhaven.py`
- [Home chat](https://github.com/felsyn/felhaven/blob/main/metis_toolbox/panels/home_panel.py): `metis_toolbox/panels/home_panel.py`
- [Dashboard views](https://github.com/felsyn/felhaven/tree/main/metis_toolbox/panels): `metis_toolbox/panels`

### Shared infrastructure

- [Audio output](https://github.com/felsyn/felhaven/blob/main/metis_toolbox/harmonia.py): `metis_toolbox/harmonia.py`
- [Kairos workers](https://github.com/felsyn/felhaven/blob/main/metis_toolbox/kairos.py): `metis_toolbox/kairos.py`
- [Secrets gate](https://github.com/felsyn/felhaven/blob/main/metis_toolbox/cerberus.py): `metis_toolbox/cerberus.py`

### Assistant workflow

- [Pythia](https://github.com/felsyn/felhaven/blob/main/metis_toolbox/pythia.py): `metis_toolbox/pythia.py`
- [Tool handlers](https://github.com/felsyn/felhaven/tree/main/metis_toolbox/tools): `metis_toolbox/tools`
- [Calliope narration](https://github.com/felsyn/felhaven/blob/main/metis_toolbox/calliope.py): `metis_toolbox/calliope.py`

### Tool capabilities

- [Weather](https://github.com/felsyn/felhaven/blob/main/metis_toolbox/tools/aura.py): `metis_toolbox/tools/aura.py`
- [Sky and seasons](https://github.com/felsyn/felhaven/tree/main/metis_toolbox/tools): `metis_toolbox/tools`
- [Local chart](https://github.com/felsyn/felhaven/blob/main/metis_toolbox/tools/artemis.py): `metis_toolbox/tools/artemis.py`
- [Markets ledger](https://github.com/felsyn/felhaven/blob/main/metis_toolbox/tools/midas.py): `metis_toolbox/tools/midas.py`
- [RSS news](https://github.com/felsyn/felhaven/blob/main/metis_toolbox/tools/pheme.py): `metis_toolbox/tools/pheme.py`
- [YouTube audio](https://github.com/felsyn/felhaven/blob/main/metis_toolbox/tools/morpheus.py): `metis_toolbox/tools/morpheus.py`
- [Tasks and utilities](https://github.com/felsyn/felhaven/tree/main/metis_toolbox/tools): `metis_toolbox/tools`
- [Markdown archive](https://github.com/felsyn/felhaven/blob/main/metis_toolbox/tools/herodotus.py): `metis_toolbox/tools/herodotus.py`
- [Web search](https://github.com/felsyn/felhaven/blob/main/metis_toolbox/tools/callimachus.py): `metis_toolbox/tools/callimachus.py`

### Other components

- **User**
- **Ollama LLM**

## Connections

- User → Home chat: asks
- User → Dashboard views: selects view
- Felhaven app → Dashboard views: renders
- Home chat → Pythia: asks
- Pythia → Ollama LLM: sends chat
- Ollama LLM → Pythia: returns reply
- Pythia → Tool handlers: dispatches calls
- Tool handlers → Weather: handles
- Tool handlers → Sky and seasons: handles
- Tool handlers → Local chart: handles
- Tool handlers → Markets ledger: handles
- Tool handlers → RSS news: handles
- Tool handlers → YouTube audio: handles
- Tool handlers → Tasks and utilities: handles
- Tool handlers → Markdown archive: handles
- Tool handlers → Web search: handles
- Home chat → Calliope narration: requests speech
- Calliope narration → Audio output: sends PCM
- Kairos workers → Tool handlers: polls fetch
- Kairos workers → Dashboard views: updates panels
- Dashboard views → Secrets gate: gates secrets
- Dashboard views → Markets ledger: shows holdings