docs/modules/M08-ui.md

M08 — UI (Gradio Dashboard + Mobile Client)

Spec version: v1.0 Depends on: M03 (bus, the ONLY data source the UI talks to), X03 (observability, for trace display), X04 (config), M09 (emergency state subscribed), gradio>=6.0.0 Depended on by: M13 (onboarding extends the UI), M12 (CLI may launch UI)

The UI's strict rule: it never imports a service module. Every piece of data comes via bus.call(...) or via the bus's introspection APIs (topology_snapshot, recent_traces). This keeps the UI swappable.

---

1. Responsibility

Present a local-host web UI at http://127.0.0.1:7860 showing:

• Live topology of the mesh
• An "ask" pane wired to llm.chat + rag.query
• A chat tab for direct messages
• A marketplace tab
• A files tab
• An emergency tab (visible only when offline)
• A settings tab
• A mobile web client served at /mobile

---

2. File layout

hearthnet/ui/
├── __init__.py
├── app.py                  # build_ui(): assembles Gradio Blocks
├── topology.py             # Cytoscape.js-backed topology component
├── theme.py                # Colour tokens, fonts, CSS
├── onboarding.py           # M13 owns this; reachable from settings
├── tabs/
│   ├── __init__.py
│   ├── ask.py              # LLM passthrough with optional RAG
│   ├── chat.py             # direct messages
│   ├── marketplace.py
│   ├── files.py
│   ├── emergency.py        # only mounted when offline state active
│   └── settings.py
└── mobile/                 # served as static at /mobile
    ├── index.html
    ├── app.js
    └── style.css

---

3. Public API

3.1 app.py

# hearthnet/ui/app.py
import gradio as gr

class UiApp:
    def __init__(
        self,
        bus: CapabilityBus,
        state_bus: StateBus,                # M09
        config: UiConfig,
        node_id_short: str,
        community_name: str,
    ):
        ...

    def build(self) -> gr.Blocks:
        """Assemble the full UI."""

    async def launch_async(self) -> None:
        """Non-blocking launch. Used by node.py."""

    async def shutdown(self) -> None: ...

def build_ui(bus, state_bus, config, **meta) -> UiApp:
    """Convenience constructor used by node.py."""

3.2 topology.py

# hearthnet/ui/topology.py
class TopologyComponent:
    """Wraps Cytoscape.js inside a Gradio HTML component.
       Auto-refreshes from bus.topology_snapshot() every 2s.
       Animates recent trace events (last 10s) along edges."""

    def __init__(self, bus: CapabilityBus): ...

    def render(self) -> gr.HTML: ...

    def push_trace(self, event: CallTraceEvent) -> None:
        """Trigger an edge animation. Color by capability prefix."""

    def push_topology(self, snapshot: TopologySnapshot) -> None: ...

# Cytoscape config:
# - Nodes: one per known peer + one for self
# - Edges: dynamic; appear on trace events; fade after 5s
# - Edge colour:  llm.*=teal,  rag.*=purple,  file.*=amber,
#                 chat.*=blue, market.*=green, community.*=grey
# - Node colour:  online=green, stale=amber, offline=red
# - Node label:   display_name + capability badges
# - On node click: side panel shows full manifest

---

4. Composition

The Gradio Blocks tree:

gr.Blocks(theme=hearthnet_theme, title="HearthNet")
├── header bar
│   ├── community name + node display name
│   ├── status pill (online/offline) → bound to state_bus
│   └── settings gear
├── topology pane (always visible at top)
└── tabs:
    ├── Ask          (always)
    ├── Chat         (always; badge with unread count)
    ├── Marketplace  (always)
    ├── Files        (always)
    ├── Notfall      (visible only when state.mode != "online")
    └── Settings     (always; includes Onboarding entry point)

---

5. Tabs

5.1 Ask tab — tabs/ask.py

A simple chat interface:

• Top: Corpus selector (dropdown, populated via bus.call("rag.list_corpora", ...))
• Top right: Model selector (capabilities from bus.topology_snapshot().capabilities_* filtered by name=llm.chat)
• Centre: Chat history (Gradio Chatbot)
• Bottom: Input + Send

Behaviour on send:

1. if corpus selected:
   chunks = bus.call("rag.query", (1,0), {params:{corpus}, input:{query:msg, k:5}})
   build system prompt with chunks + sources
2. messages = [system_with_chunks, ...history, user_msg]
3. stream = bus.stream("llm.chat", (1,0), {params:{model}, input:{messages, stream:true}})
4. accumulate tokens into a streaming response in the Chatbot
5. on done: append sources panel (clickable to open file)

5.2 Settings tab — tabs/settings.py

• Node identity (read-only)
• Community membership (read-only; "leave community" with double-confirm)
• LLM backend list (read-only; edit via config.toml)
• Theme toggle (Hearth / Spark dark mode)
• Debug toggles (verbose logging, trace ring buffer dump)
• Onboarding entrypoints: "Create new community", "Join via invite"
• Privacy: "Erase all data" (triple-confirm, wipes keys + state)

5.3 Chat tab — tabs/chat.py

• Left: peer list with last-message timestamps, unread badges
  • Source: bus.call("chat.history", (1,0), {input:{}}) → group by peer
• Right: message thread for selected peer
  • Auto-refresh on local pubsub topic chat.message.<our_short_id>
• Bottom: input + send + attachment button (opens file picker → uploads as blob via file.put → attaches CID)
• "Encrypted" indicator placeholder (Phase 2)

5.4 Marketplace tab — tabs/marketplace.py

• Top: Category filter, tag filter, search box (semantic)
• Centre: Cards (one per post)
• Bottom-right: "Neuer Beitrag" → modal for new post
• "Mark fulfilled" / "Withdraw" on each card if author == us

5.5 Files tab — tabs/files.py

• Left: corpus / pinned / recent
• Centre: file grid
• Upload area at top
• Click: preview (image / PDF / text), download, advertise to peers

5.6 Emergency tab — tabs/emergency.py

Visible only when state_bus.current().mode != "online". Designed for big buttons, low-stress reading. Large amber banner at top.

Contents:

• Big "Was tun?" button → opens the most relevant corpus (default niederrhein-emergency)
• Neighbour list (last seen times prominent)
• Direct chat shortcut
• "Update" indicator: how far behind the event log we are vs. last sync
• Shared resources table (generator availability, water, light) — Phase 2

5.7 Banner

INTERNET OFFLINE — LOKAL AKTIV
seit 14:32 · 3 Nachbar*innen erreichbar

When degraded:

EINGESCHRÄNKTE VERBINDUNG · Lokale Dienste aktiv

---

6. Mobile client (mobile/)

Plain static HTML + JS, no framework. Served by X01 at /mobile/*. Same bus API (signed requests, but credentials stored in IndexedDB).

Minimum features:

• Ask (LLM passthrough)
• Chat
• Marketplace browse
• Emergency mode banner
• No topology viz (too dense for small screen)

Auth on mobile: the user scans an invite QR with the camera → key derived in WebCrypto → stored in IndexedDB.

---

7. Theming (theme.py)

Two themes:

• Hearth (default) — warm, parchment background, dark walnut accents
• Spark (high-contrast / dark) — black bg, amber accents — also the emergency theme

CSS variables:

--hn-bg:         #f4ead7;  /* hearth */
--hn-bg-dark:    #1a1816;  /* spark */
--hn-accent:     #b45309;  /* amber */
--hn-accent-2:   #14b8a6;  /* teal */
--hn-accent-3:   #6d28d9;  /* purple, used for rag */
--hn-text:       #2c1810;
--hn-text-dark:  #f4ead7;
--hn-error:      #b91c1c;
--hn-warn:       #d97706;
--hn-ok:         #15803d;

When emergency mode is active, theme switches to Spark with amber accents and the banner.

---

8. Behaviour

8.1 Topology refresh

Every 2 s the topology component calls bus.topology_snapshot(). Diff with previous; only changed nodes/edges trigger re-render. Trace ring is read via bus.recent_traces(50) every 1 s and pushed as animations.

8.2 Live updates without polling

Where possible the UI subscribes:

• state_bus.subscribe() for emergency banner
• bus.registry.subscribe() for topology pane (additive)
• Pubsub marketplace.post.created for marketplace tab live refresh
• Pubsub chat.message.<our_short_id> for chat tab notifications

8.3 Error display

• Capability call errors → toast at top with code and "details" expander
• Backend warm-up takes time → spinner with "Modell wird geladen ..."
• Network failures during a stream → frame "verbindung abgerissen" injected; user can retry

8.4 Settings persistence

Settings tab edits go to config.toml via X04 §3. Some require restart; UI clearly indicates this.

8.5 First-run handoff to M13

If on startup config.community.community_id is None, the UI redirects to onboarding (see M13) instead of showing tabs.

---

9. Configuration

From X04 §3:

config.ui.host             # 127.0.0.1
config.ui.port             # 7860
config.ui.launch_browser   # auto-open in browser on launch

---

10. Tests

Unit

• test_theme_tokens_present
• test_emergency_tab_hidden_when_online
• test_emergency_tab_shown_when_offline
• test_topology_diff_avoids_unchanged_render (mock bus)
• test_settings_writes_to_config_file_atomically

Integration

• test_ask_tab_does_rag_then_llm_in_order — mock bus, observe call sequence
• test_marketplace_tab_refreshes_on_pubsub_event
• test_mobile_endpoint_serves_index_html

Manual

• Demo dry-run script: open UI, type query, observe topology animation, unplug WAN, observe banner ≤ 5s. Document in tests/demo_script.md.

---

11. Cross-references

What	Where
Bus introspection APIs	M03 §3.7
Emergency state source	M09 §3.1
Pubsub topics	CONTRACT §8
Onboarding flow	M13
Mobile served by	X01 §3.2
Trace event format	M03 §3.6

---

12. Open questions

1. Gradio version compatibility — Gradio 6.x evolves quickly. Pin a minor.
2. Native mobile — Phase 2 (Flutter or React Native). Web works for hackathon.
3. Accessibility — colour contrast meets WCAG AA in both themes; not yet audited.
4. Internationalisation — UI strings in German + English. Switchable. Plattdeutsch as a stretch.
5. Cytoscape vs D3 — Cytoscape preferred (less code). Performance budget: 50 nodes, 500 edges.