# fabbricate-it-solutions/klar-ha-nlu architecture

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

- Interactive diagram: https://gitdiagram.com/fabbricate-it-solutions/klar-ha-nlu
- Repository: https://github.com/fabbricate-it-solutions/klar-ha-nlu

## Overview

Klar NLU is a deterministic, multilingual Home Assistant voice-control engine, exposed through a Home Assistant Assist integration and an operator web UI. The main workflow sends an utterance through the integration to the Rust engine, which interprets it using language resources, the effective home graph, and session context, then returns an intent or clarification for Home Assistant. The README documents a second Wyoming interface and mapping, lab, policy, conversation, and settings capabilities. The graph reflects those documented branches; source excerpts were partial, so uncertain internal wiring is omitted.

Main entry points: [`src/nlu/pipeline.rs`](https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/nlu/pipeline.rs) (NLU pipeline), [`src/io/web.rs`](https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/io/web.rs) (HTTP API), [`src/io/wyoming.rs`](https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/io/wyoming.rs) (Wyoming API), [`web/src/App.tsx`](https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/web/src/App.tsx) (Operator UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Interfaces"]
  node_assist_agent["Assist agent<br/>[conversation.py]"]
  node_integration_http["Engine client<br/>[engine_http.py]"]
  node_engine_api["HTTP API<br/>[web.rs]"]
  node_wyoming_api["Wyoming API<br/>[wyoming.rs]"]
  node_runtime_state["Runtime state<br/>[state.rs]"]
end

subgraph group_interpretation["Interpretation"]
  node_nlu_pipeline["NLU pipeline<br/>[pipeline.rs]"]
  node_parser["Intent parsing<br/>[mod.rs]"]
  node_language_packs["Language packs<br/>[mod.rs]"]
  node_intent_types["Intent outcomes<br/>[intent.rs]"]
  node_session["Conversation session<br/>[session.rs]"]
end

subgraph group_home_context["Home Context"]
  node_home_graph["Effective home graph<br/>[mod.rs]"]
  node_home_sync["HA home sync<br/>[home_sync.rs]"]
end

subgraph group_operator["Operator UI"]
  node_operator_ui["Operator UI<br/>[App.tsx]"]
  node_ui_api["UI API client<br/>[api.ts]"]
  node_mapping_views["Mapping and lab"]
end

subgraph group_optional_llm["Optional LLM"]
  node_llm_assist["LLM assist<br/>[assist.rs]"]
  node_llm_client["LLM client<br/>[client.rs]"]
end

node_assist_user(("Voice user"))
node_home_assistant["Home Assistant"]
node_llm_provider["LLM provider"]

node_assist_user -->|"speaks to"| node_home_assistant
node_home_assistant -->|"routes Assist"| node_assist_agent
node_assist_agent -->|"requests parse"| node_integration_http
node_integration_http -->|"posts utterance"| node_engine_api
node_engine_api -->|"invokes parsing"| node_nlu_pipeline
node_wyoming_api -->|"invokes parsing"| node_nlu_pipeline
node_nlu_pipeline -->|"analyzes text"| node_parser
node_nlu_pipeline -->|"uses locale"| node_language_packs
node_nlu_pipeline -->|"reads targets"| node_home_graph
node_nlu_pipeline -->|"reads and updates"| node_session
node_nlu_pipeline -->|"returns outcome"| node_intent_types
node_engine_api -->|"uses shared state"| node_runtime_state
node_wyoming_api -->|"uses shared state"| node_runtime_state
node_home_assistant -->|"provides registry data"| node_home_sync
node_home_sync -->|"updates graph"| node_home_graph
node_operator_ui -->|"requests data"| node_ui_api
node_ui_api -->|"calls endpoints"| node_engine_api
node_operator_ui -->|"shows tools"| node_mapping_views
node_llm_assist -.->|"requests completion"| node_llm_client
node_llm_client -.->|"sends chat request"| node_llm_provider

click node_assist_agent "https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/custom_components/klar_nlu/conversation.py"
click node_integration_http "https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/custom_components/klar_nlu/engine_http.py"
click node_engine_api "https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/io/web.rs"
click node_wyoming_api "https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/io/wyoming.rs"
click node_runtime_state "https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/io/state.rs"
click node_nlu_pipeline "https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/nlu/pipeline.rs"
click node_parser "https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/parse/mod.rs"
click node_language_packs "https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/lang/mod.rs"
click node_intent_types "https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/types/intent.rs"
click node_session "https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/session.rs"
click node_home_graph "https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/home/mod.rs"
click node_home_sync "https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/io/home_sync.rs"
click node_operator_ui "https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/web/src/App.tsx"
click node_ui_api "https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/web/src/api.ts"
click node_mapping_views "https://github.com/fabbricate-it-solutions/klar-ha-nlu/tree/main/web/src/pages"
click node_llm_assist "https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/llm/assist.rs"
click node_llm_client "https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/llm/client.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_assist_agent,node_integration_http,node_engine_api,node_wyoming_api,node_runtime_state,node_assist_user toneBlue
class node_nlu_pipeline,node_parser,node_language_packs,node_intent_types,node_session toneAmber
class node_home_graph,node_home_sync toneMint
class node_operator_ui,node_ui_api,node_mapping_views toneRose
class node_llm_assist,node_llm_client,node_home_assistant,node_llm_provider toneIndigo
```

## Components

### Interfaces

- [Assist agent](https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/custom_components/klar_nlu/conversation.py): `custom_components/klar_nlu/conversation.py`
- [Engine client](https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/custom_components/klar_nlu/engine_http.py): `custom_components/klar_nlu/engine_http.py`
- [HTTP API](https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/io/web.rs): `src/io/web.rs`
- [Wyoming API](https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/io/wyoming.rs): `src/io/wyoming.rs`
- [Runtime state](https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/io/state.rs): `src/io/state.rs`

### Interpretation

- [NLU pipeline](https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/nlu/pipeline.rs): `src/nlu/pipeline.rs`
- [Intent parsing](https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/parse/mod.rs): `src/parse/mod.rs`
- [Language packs](https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/lang/mod.rs): `src/lang/mod.rs`
- [Intent outcomes](https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/types/intent.rs): `src/types/intent.rs`
- [Conversation session](https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/session.rs): `src/session.rs`

### Home Context

- [Effective home graph](https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/home/mod.rs): `src/home/mod.rs`
- [HA home sync](https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/io/home_sync.rs): `src/io/home_sync.rs`

### Operator UI

- [Operator UI](https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [UI API client](https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/web/src/api.ts): `web/src/api.ts`
- [Mapping and lab](https://github.com/fabbricate-it-solutions/klar-ha-nlu/tree/main/web/src/pages): `web/src/pages`

### Optional LLM

- [LLM assist](https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/llm/assist.rs): `src/llm/assist.rs`
- [LLM client](https://github.com/fabbricate-it-solutions/klar-ha-nlu/blob/main/src/llm/client.rs): `src/llm/client.rs`

### Other components

- **Voice user**
- **Home Assistant**
- **LLM provider**

## Connections

- Voice user → Home Assistant: speaks to
- Home Assistant → Assist agent: routes Assist
- Assist agent → Engine client: requests parse
- Engine client → HTTP API: posts utterance
- HTTP API → NLU pipeline: invokes parsing
- Wyoming API → NLU pipeline: invokes parsing
- NLU pipeline → Intent parsing: analyzes text
- NLU pipeline → Language packs: uses locale
- NLU pipeline → Effective home graph: reads targets
- NLU pipeline → Conversation session: reads and updates
- NLU pipeline → Intent outcomes: returns outcome
- HTTP API → Runtime state: uses shared state
- Wyoming API → Runtime state: uses shared state
- Home Assistant → HA home sync: provides registry data
- HA home sync → Effective home graph: updates graph
- Operator UI → UI API client: requests data
- UI API client → HTTP API: calls endpoints
- Operator UI → Mapping and lab: shows tools
- LLM assist → LLM client: requests completion
- LLM client → LLM provider: sends chat request