wifi-densepose/v2/crates/homecore-server

homecore-server

Integrated HOMECORE server binary that wires state machine, API, recorder, plugins, automations, intent assistant, and HomeKit bridge into one process.

The production-ready HOMECORE binary — boots all 7 subsystems (core, API, recorder, plugins, automation, assist, HAP bridge) in a single process listening on :8123.

What this crate does

homecore-server is the integration point for the entire HOMECORE ecosystem. It orchestrates:

1. HomeCore runtime — state machine, event bus, service registry
2. REST + WebSocket API — Axum server on :8123 (HA-compatible)
3. SQLite Recorder — persists all state changes to disk
4. Plugin Registry — loads and manages integrations (InProcessRuntime by default)
5. Automation Engine — evaluates triggers, conditions, and actions
6. Assist Pipeline — intent recognition and execution
7. HAP Bridge — exposes accessories to HomeKit

All subsystems share the same HomeCore instance, so state changes flow through the event bus and trigger automations, record history, and notify WebSocket subscribers in lockstep.

Features

• Single unified process — no external microservices; run with cargo run -p homecore-server
• HA-compatible REST API — drop-in replacement for Home Assistant's /api/ on :8123
• SQLite state history — persistent recording of all state changes
• Automation engine — YAML-driven trigger→condition→action execution
• Intent assistant — regex-based (P1) intent recognition + service calling
• HomeKit bridge — exposes HOMECORE entities as HomeKit accessories
• Plugin system — load first-party Rust plugins; Wasmtime WASM plugins (P2, --features wasmtime)
• Configurable via CLI + env vars — no YAML required; sensible defaults
• Structured logging — tracing output with RUST_LOG filtering
• Feature-gated subsystems — disable recorder (--no-recorder), enable ruvector/wasmtime as needed

Subsystems

Subsystem	Crate	Role	Notes
State Machine	homecore	Core domain model	All other subsystems depend on this
REST API	homecore-api	HTTP boundary	Listens on :8123; Axum framework
Recorder	homecore-recorder	Persistence	SQLite; optional --no-recorder
Plugins	homecore-plugins	Extension system	InProcessRuntime default; Wasmtime w/ feature
Automation	homecore-automation	Trigger execution	Subscribes to event bus; YAML-driven
Assist	homecore-assist	Intent pipeline	Regex recognizer (P1); semantic (P2)
HAP Bridge	homecore-hap	HomeKit export	Accessories + characteristics; mDNS (P2)

Usage

Basic startup (in-memory recorder):

cargo build -p homecore-server
./target/debug/homecore-server
# Listens on http://localhost:8123

With persistent SQLite:

./target/debug/homecore-server \
  --bind 0.0.0.0:8123 \
  --db sqlite:~/.homecore/home.db \
  --location-name "My Home"

Full feature build (ruvector semantic search + Wasmtime plugins):

cargo build -p homecore-server --features ruvector,wasmtime --release

Via Docker (Dockerfile planned P2):

docker run -p 8123:8123 \
  -e HOMECORE_DB=sqlite:///data/home.db \
  -v ~/.homecore:/data \
  homecore-server:latest

Test the API:

# List all entities
curl http://localhost:8123/api/states

# Set a light to "on"
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"state":"on","attributes":{"brightness":200}}' \
  http://localhost:8123/api/states/light.kitchen

# WebSocket subscription (real-time state changes)
wscat -c ws://localhost:8123/api/websocket

Configuration via env:

export HOMECORE_BIND="0.0.0.0:8123"
export HOMECORE_DB="sqlite:~/.homecore/home.db"
export HOMECORE_LOCATION="Living Room"
export RUST_LOG="homecore=debug,homecore_api=info"
./target/debug/homecore-server

CLI Options

Flag	Env Var	Default	Description
--bind	HOMECORE_BIND	0.0.0.0:8123	REST API listen address
--db	HOMECORE_DB	sqlite::memory:	SQLite path (:memory: for ephemeral)
--location-name	HOMECORE_LOCATION	Home	Friendly name returned by /api/config
--no-recorder	—	off	Disable SQLite recorder (low-resource deployments)
--ui-dir	HOMECORE_UI_DIR	<crate>/ui	HOMECORE-UI asset dir served at /homecore (ADR-131); empty disables the mount

HOMECORE-UI dashboard (ADR-131)

This binary also serves the HOMECORE-UI — the complete operational dashboard for the two-tier Cognitum stack (v0 Appliance → SEEDs → ESP32 nodes) — at /homecore, alongside the HA-compat /api surface. It is a zero-dependency, no-build-step vanilla TS/JS + CSS frontend living in ui/:

cargo run -p homecore-server          # then open http://localhost:8123/homecore/

It drives the live /api + /api/websocket (subscribe_events) endpoints; panels backed by services not in this binary (SEED HTTPS API, calibration ADR-151, federation ADR-105) render against a DEMO-flagged contract-conformant mock until those endpoints land (ADR-131 §7.1). Frontend tests + benchmark run under plain node (no npm install):

cd ui && npm test     # import graph + render-smoke + interaction (24 checks)
cd ui && npm run bench # bundle budget (~137 KB, ~37× smaller than HA) + render timing

Comparison to Home Assistant

Aspect	Home Assistant	homecore-server
Architecture	Python asyncio monolith	Rust async Tokio + component traits
API protocol	/api/ REST (HA wire format)	Identical HA wire format
Persistence	SQLite + YAML files	SQLite (P1); Redis (P2)
Plugins	Python integrations in homeassistant/components/	Rust (P1) + WASM (P2)
Automation execution	Python asyncio event loop	Tokio async tasks + trait-based
HomeKit bridge	Via homekit integration	Built-in homecore-hap subsystem
CLI	hass command with config YAML	homecore-server with feature flags
Scalability	Single instance (HA Cloud for scale)	Can be load-balanced (future)
Binary size	~200 MB (Python + deps)	~50 MB (Rust, release build; 200 MB w/ wasmtime)

Performance Targets (unreleased; TBD)

• Startup time — < 2s to listen on :8123
• REST endpoint latency — p50 < 1 ms; p99 < 10 ms
• Event bus throughput — 10,000+ events/sec
• Automation evaluation — < 100 μs per trigger
• Concurrent WebSocket connections — 10,000+
• Memory footprint — ~100 MB (idle); ~500 MB with 1,000 recorded states

Development

Run tests:

cargo test -p homecore-server

Enable debug logging:

RUST_LOG=debug cargo run -p homecore-server -- --bind 127.0.0.1:8123

Build documentation:

cargo doc -p homecore-server --open

Relation to other HOMECORE crates

homecore-server (orchestration binary)
├── homecore (state machine)
├── homecore-api (REST + WS)
├── homecore-recorder (SQLite persistence)
├── homecore-plugins (extension system)
├── homecore-automation (trigger execution)
├── homecore-assist (intent pipeline)
└── homecore-hap (HomeKit bridge)

References

• ADR-126: HOMECORE Home Assistant Port (master)
• README — wifi-densepose
• Dockerfile (planned P2)
• Docker Hub image (planned P2)