# Central AI Hub — System Overview

> **Writing Style**: ASD-STE100 Simplified Technical English (`ste-writing`).

## Purpose

The Hub is one service. Every way in reaches every ability through the Hub. Build
each ability once. All ways in get it.

Today, Jervis (voice) and dsh (chat) each understand the user and act. A third
way in, the phone app, would repeat the same work. The Hub stops this repeat.

## The Five Steps

1. **Hear** — take voice or text from any way in.
2. **Understand** — the LLM works out what the user asked.
3. **Check** — test whether the user may ask for this.
4. **Route** — send the request to one destination.
5. **Answer** — return a short reply in the right shape.

When the question is about another project's data, step 4 asks that project
through the `/ask` contract. See `docs/ask-contract.md`.

## Three Directions

Nothing here is ownership. These are directions of talk.

1. The Hub asks a project.
2. A project tells the Hub.
3. n8n triggers the project.

## Ways In

- Phone app (Kotlin) — wake word, voice, controls.
- Admin app (Kotlin) — restricted actions only.
- ESP32 voice — "Hey Jervis".
- dsh chat — per-person chat.
- Console portal — web dashboard.

The admin app is also the trusted door. It calls a high-consequence control
service directly, not through the Hub.

## Peers and Destinations

Every other project is a peer. Each has its own folder, repo, port, and
interface. Each works without the Hub.

| Peer | Talk direction |
|---|---|
| Email agent | Hub asks it. It tells the Hub. n8n scans it. |
| Compass / NHS | Hub asks it. It tells the Hub. n8n scans it. |
| Internet control | Hub asks it. Control goes through its own apps. |
| Artemis | Hub calls it to act. Nothing comes back. |
| Home Assistant | Hub calls it to act. |
| Speakers (Jervis) | Hub calls it to speak. |
| Paperclip | Hub files jobs. The answer returns. |
| Web search | Hub calls it. |
| Apprise / NTFY | Hub calls it to notify. |

## Query, Command, or Control

| Kind | Path | Confirm |
|---|---|---|
| Query | Hub asks a project (`/ask`) | No |
| Command | Hub calls Home Assistant | No |
| Control | Admin app calls internet control | Yes, on the phone |

A high-consequence control does not route through the Hub.

## Routing

The Hub picks a project with three things: a capability list from each project, a
human-editable `routing.md`, and an LLM. The LLM returns one of four answers:
route, fanout, clarify, or no_match. When it is unsure, it asks the user a short
question. It never routes a control action.

## Observability

The Hub writes one append-only log. It records the request, the route, the project
asked, and the latency. The log is capped. It holds no secrets.

## Reply Shapes

The Hub returns one reply. The reply can hold text, spoken audio (TTS), Artemis
commands, a notification, or an email. TTS can play on the house speakers or on
the phone. The Hub returns the reply to the source.

## The Dividing Line

The Hub asks one question: does this need a decision, or does it need to happen?

- **Happen** — fast and certain. Go straight to the destination. No LLM in the
  path of the action.
- **Decision** — slow, multi-step, worth recording. Send to Paperclip.

## What the Hub Is Not

- Not a central brain. No single personality or memory.
- Not Paperclip. The Hub does not wait minutes for an answer.
- Not a destination. The Hub does not turn off the internet itself.
- Not an owner. The other projects are peers, not sub-projects.