Skip to main content

Helpifyr Fabric Architecture

Documentation Map​

Helpifyr Fabric Architecture

Summary​

helpifyr-fabric is the shared control-plane Service for Helpifyr.

System model:

  • Fabric Core owns shared orchestration state
  • Dapr provides invocation and state plumbing
  • NATS JetStream provides durable async propagation
  • MCP exposes safe operator and agent access

Architectural Goals​

  • centralize orchestration truth without product business logic drift
  • keep provider logic behind adapters
  • preserve durable delivery through n8n-operator and JetStream
  • preserve product ownership boundaries for clawledger and mission-control
  • stay extensible for additional products and providers

Layered Model​

Fabric Core​

The Fabric Core owns:

  • work-intake normalization
  • task and capability classification
  • team and sub-agent setup generation
  • communication graph ownership
  • trust and route policy
  • topology intent
  • graph revisions
  • rollout planning
  • drift detection
  • audit state
  • provider registry
  • product registry
  • governance hooks

Dapr Layer​

Dapr is used for:

  • service invocation between Fabric and adapters
  • state-store abstraction
  • pub/sub connectivity
  • secrets and configuration integration
  • optional workflow-style orchestration where it simplifies coordination

The current HF-010 baseline is now beyond stack-only intent: the Fabric exposes a host-verified Dapr runtime/status surface, a state-store probe, an invocation self-probe, and operator-facing readiness and dashboard views that confirm the middleware layer is ready for the next integration step.

Current Dapr baseline references:

  • Dapr baseline runbook (docs/docs/operations/DAPR_BASELINE_RUNBOOK.md)
  • HF-010 issue status (docs/docs/issues/HF-010-dapr-backed-invocation-and-state-usage.md)

This middleware baseline is now documented end-to-end as a repo-wide handoff path for the next HF-010 integration layer.

NATS JetStream Layer​

JetStream is the durable event and async backbone.

Primary event families include:

  • topology-changed
  • rollout-planned
  • rollout-applied
  • drift-detected
  • product-sync-requested
  • product-sync-succeeded
  • product-sync-failed
  • approval-required
  • residual-risk-detected

MCP Layer​

MCP is exposed as a safe edge surface for:

  • topology reads
  • setup previews
  • drift summaries
  • rollout previews
  • guarded actions
  • diagnostics

Provider Model​

Fabric treats orchestrators as providers behind a stable contract.

Required provider capabilities include:

  • discover_runtime
  • list_agents
  • read_topology
  • validate_graph
  • plan_patch
  • apply_patch
  • verify_apply
  • list_capabilities

V1 Provider​

  • openclaw

Planned Future Providers​

  • nemo-claw
  • additional orchestration systems
  • later autonomy runtimes

Product Adapter Model​

Fabric exposes product adapters for consumers of orchestration intelligence.

V1 Product Adapters​

  • mission-control
  • clawledger
  • n8n-operator
  • openclaw-mem0-localai-kit

Each product adapter should declare:

  • supported task/setup profiles
  • required verification modes
  • trust expectations
  • downstream sync contract
  • operator-facing summary model

Integration Responsibilities​

n8n-operator​

Fabric owns:

  • intended communication graph
  • trust and route policy
  • graph revisions
  • sync history
  • topology intent
  • fixture-first example contract discovery and onboarding artifacts for downstream harnesses
  • stable example metadata, capabilities, bootstrap, and evidence/history endpoints documented consistently across the repo

n8n-operator owns:

  • durable delivery
  • mailbox/NATS path
  • callback contracts
  • runtime-safe dispatch and recovery
  • actual communication execution

For non-live consumer bootstrapping, the n8n-operator contract surface also exposes:

  • example artifact discovery through /api/v1/products/n8n-operator/sync/examples
  • ordered fixture consumption through /api/v1/products/n8n-operator/sync/examples/manifest
  • stable example metadata, capabilities, bootstrap, and evidence/history endpoints for contract tests and onboarding flows

clawledger​

ClawLedger should consume setup guidance from Fabric, not invent orchestration shape locally.

Fabric should supply profiles such as:

  • finance-domain
  • approval-heavy
  • simulation-harness
  • live-adjacent smoke
  • RC hardening

mission-control​

Mission Control should become the human operator shell over Fabric:

  • setup preview
  • topology view
  • drift view
  • rollout view
  • audit view

Governance and Solarisara Readiness​

Current architecture boundary:

  • keep governance hooks, approval metadata, and residual-risk records in Fabric
  • keep full Solarisara council/runtime logic out of this repo until a later phase

Target Repository Structure​

helpifyr-fabric/
├── src/helpifyr_fabric/core
├── src/helpifyr_fabric/api
├── src/helpifyr_fabric/providers
├── src/helpifyr_fabric/products
├── src/helpifyr_fabric/events
├── src/helpifyr_fabric/governance
├── src/helpifyr_fabric/persistence
├── src/helpifyr_fabric/mcp
└── src/helpifyr_fabric/sdk

Recommended v1 packages:

  • providers/openclaw
  • products/mission_control
  • products/clawledger
  • products/n8n_operator
  • products/openclaw_mem0

Future placeholders:

  • providers/nemo_claw
  • products/news_memory
  • products/jadda_mobile
  • governance/solarisara_spine

License​