docs/ARCHITECTURE.md

HearthNet — Architecture Reference

Local-first community AI mesh. Each participant runs a node on their own hardware. Nodes discover each other automatically and share AI capabilities, files, and community posts — no central server required.

---

High-Level Concept

┌──────────────────────────────────────────────────────────────────────────┐
│                         Community Mesh (LAN / overlay)                    │
│                                                                           │
│   ┌─────────────┐    mDNS/UDP     ┌─────────────┐    mDNS/UDP            │
│   │  Node A     │◄───────────────►│  Node B     │◄──────────────         │
│   │  (anchor)   │                 │  (hearth)   │                         │
│   │             │   capability    │             │                         │
│   │  CapBus ◄───┼─────bus.call───►─►  CapBus   │                         │
│   │  LLM svc    │                 │  RAG svc    │                         │
│   │  RAG svc    │                 │  OCR svc    │                         │
│   │  Gradio UI  │                 │  Gradio UI  │                         │
│   └─────────────┘                 └─────────────┘                         │
└──────────────────────────────────────────────────────────────────────────┘

HearthNet is structured around three ideas:

1. Node — a Python process on someone's hardware (Raspberry Pi, laptop, server).
2. CapabilityBus — a message bus where services register capabilities (e.g. llm.chat@1.0). Any code, local or remote, calls a capability by name.
3. Services — pure-Python objects that handle capability calls. A node installs whichever services its hardware supports.

---

Module Map

Phase 1 — Foundation

Module	Location	What it does
M01 Identity	hearthnet/identity/	Ed25519 node keys, community manifests, invite tokens
M02 Discovery	hearthnet/discovery/	mDNS + UDP multicast peer discovery
M03 Bus	hearthnet/bus/	Capability router, health ring buffer, trust levels
M04 LLM	hearthnet/services/llm/	Local model backends (Ollama, llama.cpp, LM Studio, HF, Anthropic)
M05 RAG	hearthnet/services/rag/	Chunker → embedder → Chroma vector store + retrieval
M06 Marketplace	hearthnet/services/marketplace/	Event-sourced community board (posts, offers, requests)
M07 Blobs	hearthnet/blobs/	BLAKE3 content-addressed file store with chunked transfer
M08 UI	hearthnet/ui/	Gradio 8-tab interface + themes + topology component
M09 Emergency	hearthnet/emergency/	Async probe loop → emergency state machine
M10 Chat	hearthnet/services/chat/	Event-backed direct messages between nodes
M11 Embedding	hearthnet/services/embedding/	Sentence-transformer embeddings (BAAI/bge-small)
M12 CLI	hearthnet/cli.py	Click CLI: run, call, log, rag, invite, version, …
M13 Onboarding	hearthnet/ui/onboarding.py	Invite QR flow + first-run wizard

Phase 2 — Resilience & Rich Services

Module	Location	What it does
M14 Federation	hearthnet/federation/	Cross-community node manifests + signed bridges
M15 Relay	hearthnet/relay/	Public-IP relay tier for NAT traversal
M16 Tokens	hearthnet/identity/tokens.py	AuthToken / CapabilityToken scoped access
M17 OCR	hearthnet/services/ocr/	Tesseract / TrOCR text extraction
M18 Translation	hearthnet/services/translation/	NLLB-200 local translation
M19 STT/TTS	hearthnet/services/stt_tts/	Whisper STT + Coqui/pyttsx3 TTS
M20 Vision	hearthnet/services/vision/	Florence-2 image captioning / VQA
M21 Tool Calls	hearthnet/services/tools/	LLM tool-call executor (plant ID, search, …)
M22 Mobile	hearthnet/ui/mobile/	PWA manifest + service worker for home-screen install
M23 E2E Encryption	hearthnet/crypto/	X25519 ECDH + ChaCha20-Poly1305 channel encryption
M24 Rerank	hearthnet/services/rerank/	Cross-encoder reranking for RAG results
M25 Group Chat	hearthnet/services/group_chat/	Multi-party room-based chat

Phase 3 — Experimental (opt-in via config.toml)

Module	Location	Flag	What it does
M26 Distributed Inference	hearthnet/distributed_inference/	research.distributed_inference	Layer-shard a 7B model across LAN nodes (Petals-style)
M27 MoE Routing	hearthnet/moe/	research.moe_routing	Route queries to best expert (model/service/human) via learned scorer
M28 FedLearn	hearthnet/fedlearn/	research.fedlearn	FedAvg LoRA fine-tuning without sharing raw data
M29 LoRa Beacons	hearthnet/lora/	research.lora_beacons	868 MHz offline "I'm alive" heartbeats via USB LoRa stick
M30 Evidence Graph	hearthnet/evidence/	research.evidence	Claim → attest → dispute provenance graph + EBKH bridge
M31 Civil Defense	hearthnet/civdef/	research.civil_defense	THW/DRK/KatS alert pipeline with role certs + audit chain
M32 Protocol Standard	hearthnet/services/protocol/	on by default	Protocol version list + conformance report

Cross-Cutting

ID	Location	What it does
X01 Transport	hearthnet/transport/	HTTP/SSE client, backpressure, rate limiting, frame types
X02 Events	hearthnet/events/	SQLite Lamport event log + gossip sync
X03 Observability	hearthnet/observability/	Tracing, metrics, Doctor health checks, TrackioExporter
X04 Config	hearthnet/config.py	Typed TOML config + ResearchConfig feature flags
X05 DHT	hearthnet/dht/	Kademlia-inspired DHT for cross-LAN peer lookup
X06 WebSocket	hearthnet/transport/	WebSocket pubsub (StateBus → live UI push)
X07 Federated Metrics	hearthnet/observability/	Opt-in aggregate mesh health metrics
X08 Tensor Transport	hearthnet/transport/tensor/	Chunked tensor stream for M26 distributed inference
X09 Conformance Suite	hearthnet/conformance/	21-check black-box conformance runner

---

Composition Root

HearthNode in hearthnet/node.py is the single composition root.

node = HearthNode(
    node_id="my-node",
    display_name="Alice's Pi",
    community_id="ed25519:abc123",
)
node.install_services(corpus="general")
await node.start()

install_services() registers all services the local hardware supports into the bus. Heavy optional dependencies (torch, chromadb, etc.) are imported lazily and fail gracefully — a node with no GPU still works, it just can't answer GPU-only capabilities.

---

Capability Bus

Caller ──── bus.call(name, version, body) ──────────┐
                                                     ▼
                                          ┌──────────────────┐
                                          │  CapabilityBus   │
                                          │                  │
                                          │  Registry        │
                                          │  ┌─────────────┐ │
                                          │  │ local route │─┼──► Service.handle()
                                          │  ├─────────────┤ │
                                          │  │ remote route│─┼──► HTTP POST /bus/v1/call
                                          │  └─────────────┘ │
                                          │  HealthMonitor   │
                                          │  TrustFilter     │
                                          └──────────────────┘

• Local route — service is installed on this node → direct Python call.
• Remote route — capability is advertised by a peer → HTTP POST to that peer's transport.
• Version negotiation — capabilities are registered with a (major, minor) version; the bus picks the highest compatible version.
• Health monitoring — each service's response times are tracked in a ring buffer; unhealthy services are quarantined for BUS_QUARANTINE_SECONDS.

---

Data Flow: LLM Chat Request

User types in Gradio UI
       │
       ▼
  app.py (Gradio event handler)
       │  bus.call("llm.chat@1.0", body)
       ▼
  CapabilityBus.call()
       │
       ├─ local LlmService found?
       │       │ yes → LlmService.handle() → backend.chat() → yield Token
       │       │
       └─ no local service
               │ peer has llm.chat?
               ├─ yes → HTTP POST /bus/v1/call → remote node → stream tokens back
               └─ no  → CapabilityError("not_found")

---

Discovery Flow

Node boots
    │
    ├── mDNS: register _hearthnet._tcp.local.  (LAN multicast DNS)
    ├── UDP: send announce to 224.0.0.251:7079 every 15s
    │
    ▼
PeerRegistry receives announcements from other nodes
    │
    ├── new peer → RegistryEvent(kind="added", entry=...)
    ├── peer gone (TTL expired) → RegistryEvent(kind="removed", ...)
    └── ManifestPublisher re-publishes every 300s

---

Emergency Mode

EmergencyDetector (async loop, 30s probe)
    │
    ├── probe connectivity endpoints
    │
    ├── ONLINE  → EmergencyState.NORMAL
    │                │ UI shows normal theme
    │
    └── OFFLINE → EmergencyState.EMERGENCY
                     │ UI switches to emergency theme (red)
                     │ emergency.llm.chat capability activated
                     │ LoRa beacons sent if hardware available (M29)
                     │ Civil defense alerts published if role cert present (M31)

---

MoE Expert Routing (M27)

Query arrives at any node
       │
       ▼
  MoeRouter.route(query, top_k=3)
       │
       ├── score all registered ExpertDescriptors against query
       │   (tag overlap + cosine similarity + recency weighting)
       │
       └── return ranked RouteResult
              │
              ├── expert_type="model"   → bus.call(f"llm.chat@1.0", ...) on that node
              ├── expert_type="service" → bus.call(expert_capability, ...)
              ├── expert_type="human"   → notify via chat + start handoff timer (M27 §4)
              └── expert_type="external"→ HTTP call to opt-in external API

Enable it: set research.moe_routing = true in ~/.config/hearthnet/config.toml.

---

Distributed Inference (M26 — BitTorrent-style LLM sharing)

Node A: layers 0–15 of Llama-3.2-3B
Node B: layers 16–27 of Llama-3.2-3B
Node C: layers 28–35 (lm_head) of Llama-3.2-3B
                │
                ▼
PipelineOrchestrator.plan(model_id="llama3.2:3b")
    │  → discovers shards via experimental.distributed_llm.shard.list
    │  → checks layer coverage: 0..35 ✓
    │
PipelineOrchestrator.run(pipeline, input_tokens)
    │  → sends activations A→B via X08 TensorTransport (1 MiB chunks)
    │  → B sends activations B→C
    │  → C returns final logits
    │
    └── caller gets streamed tokens like any local model

Model weights are shared chunk-by-chunk using BLAKE3 CID-addressed blob transfer — same mechanism as file blobs (M07), but optimised for .gguf / .safetensors files.

---

File Tree

hearthnet/
├── node.py                    # HearthNode — composition root
├── types.py                   # Shared type aliases (NodeID, ShardID, AlertID, …)
├── constants.py               # All numeric defaults and limits
├── config.py                  # HearthnetConfig + ResearchConfig (TOML-backed)
├── cli.py                     # Click CLI entry point
├── facades.py                 # HearthFacade — thin high-level API for app.py
├── controller.py              # HearthController — legacy thin wrapper
│
├── bus/                       # M03 CapabilityBus
│   ├── router.py              # routing logic (local → remote)
│   ├── registry.py            # CapabilityEntry, RegistryEvent, Diff
│   ├── capability.py          # CapabilityEntry dataclass
│   └── health.py              # ring-buffer health monitor
│
├── identity/                  # M01
│   ├── keys.py                # Ed25519 key generation + signing
│   ├── manifest.py            # NodeManifest, CommunityManifest, CommunityPolicy, …
│   └── tokens.py              # AuthToken, CapabilityToken
│
├── discovery/                 # M02
│   └── peers.py               # mDNS + UDP multicast PeerRegistry
│
├── transport/                 # X01 / X06 / X08
│   ├── client.py              # HTTP + SSE client
│   ├── streams.py             # Frame, SseReader
│   ├── backpressure.py        # FlowControl, RateCheck, RateLimiter
│   └── tensor/                # X08 tensor chunked transport
│
├── events/                    # X02
│   ├── log.py                 # SQLite Lamport event log
│   └── sync.py                # Gossip SyncClient / SyncServer
│
├── observability/             # X03
│   ├── tracing.py             # attach/detach trace context
│   ├── metrics.py             # MetricsCollector, TrackioExporter
│   └── doctor.py             # DoctorResult, CheckResult, DoctorService
│
├── services/                  # M04 – M21 + M32
│   ├── llm/                   # M04 — backends: ollama, llama_cpp, lmstudio, hf_api, anthropic
│   ├── rag/                   # M05
│   ├── marketplace/           # M06
│   ├── chat/                  # M10
│   ├── embedding/             # M11
│   ├── ocr/                   # M17
│   ├── translation/           # M18
│   ├── stt_tts/               # M19
│   ├── vision/                # M20
│   ├── tools/                 # M21
│   ├── group_chat/            # M25
│   └── protocol/              # M32
│
├── ui/                        # M08
│   ├── app.py                 # Gradio 8-tab entry point
│   ├── tabs/                  # one file per tab
│   ├── theme.py               # hearthnet_theme, emergency_theme
│   ├── topology.py            # TopologyComponent (mesh graph)
│   ├── onboarding.py          # first-run wizard + invite QR
│   └── mobile/                # M22 PWA manifest + service worker
│
├── emergency/                 # M09
│   ├── detector.py            # async probe loop
│   └── state.py               # EmergencyState enum
│
├── crypto/                    # M23
│   └── channel.py             # X25519 + ChaCha20-Poly1305
│
├── blobs/                     # M07
│   └── store.py               # BLAKE3 CID store + chunked reader
│
├── dht/                       # X05
├── federation/                # M14
├── relay/                     # M15
│
├── distributed_inference/     # M26 (experimental)
├── moe/                       # M27 (experimental)
├── fedlearn/                  # M28 (experimental)
├── lora/                      # M29 (experimental)
├── evidence/                  # M30 (experimental)
├── civdef/                    # M31 (experimental)
└── conformance/               # X09

---

Configuration

~/.config/hearthnet/config.toml (created on first run with defaults):

[node]
node_id      = ""          # auto-generated Ed25519 key ID
display_name = "My Node"
data_dir     = "~/.hearthnet"

[transport]
http_port    = 7080
ui_port      = 7860

[llm]
default_backend = "ollama"   # "ollama" | "llama_cpp" | "lmstudio" | "hf_api" | "smollm"

[rag]
corpus_dir      = "~/.hearthnet/corpus"
embedding_model = "BAAI/bge-small-en-v1.5"

[policy.research]
enable                  = false     # master switch for all experimental modules
moe_routing             = false     # M27
distributed_inference   = false     # M26
fedlearn                = false     # M28
lora_beacons            = false     # M29
evidence                = false     # M30
civil_defense           = false     # M31

---

Connecting a Local Node to the HF Space

The HF Space at https://huggingface.co/spaces/build-small-hackathon/HearthNet is a single-node anchor you can peer with from any local machine.

# 1. Clone and install
git clone https://huggingface.co/spaces/build-small-hackathon/HearthNet
cd HearthNet
pip install -e .

# 2. Run your local node (pick a free port if 7080 is taken)
python -m hearthnet.cli run --http-port 7080 --ui-port 7860

# 3. Manually add the HF Space anchor as a peer (different network = manual)
python -m hearthnet.cli call discovery.peer.add 1 0 \
  '{"endpoint":"https://build-small-hackathon-hearthnet.hf.space","node_id":"hf-space-anchor"}'

# 4. Verify peering
python -m hearthnet.cli call discovery.peers 1 0 '{}'

Or use the helper script:

python scripts/connect_to_hf.py

Once peered, your local node can:

• Route LLM queries from the HF Space to your local (better) model
• Push community posts that appear in the HF Space UI
• Share blob files across the connection

Note: The HF Space runs on a public server without a static IP for inbound connections. Your local node initiates the connection; the HF Space cannot discover you via mDNS. Use discovery.peer.add or the invite flow to establish the bridge manually.

---

Security Model

• Node identity — Ed25519 key pair generated locally, never leaves the device.
• Trust levels — unknown → member → trusted → anchor. Capabilities can require a minimum trust level.
• Capability scoping — AuthToken restricts which capabilities a caller may invoke.
• Channel encryption — M23 X25519 ECDH + ChaCha20-Poly1305 for inter-node transport (opt-in, defaults off).
• Experimental capabilities — Phase 3 modules are off by default and require explicit opt-in. The bus refuses to register them unless the feature flag is on.
• No central authority — there is no HearthNet.com, no certificate authority, no registration server. Trust is established peer-to-peer via invite chains.

---

Testing

# Full suite (133 unit + integration tests):
pytest tests/ -q

# Skip slow E2E browser tests:
pytest tests/ -q -k "not e2e"

# Phase 3 experimental module tests only:
pytest tests/test_phase3_experimental.py -v

# Conformance runner (X09):
python -m hearthnet.conformance.runner --output conformance-report/

---

This document is generated from the spec set in docs/. For per-module detail see:

• Phase 1+2: 00-OVERVIEW.md, CAPABILITY_CONTRACT.md, modules/M01-*.md …
• Phase 3: docs/p2_p3/IMPLEMENTATION_REFERENCE_p3.md, docs/p2_p3/M26-*.md …