Architecture

System Overview

jhf-shuttle is a Linux-first, Python-based operator tool with an optional API surface and an optional on-prem messaging path.

Primary layers:

1. n8n_expert core
   • CLI
   • validation/build/inspect logic
   • live n8n API operations
   • upgrade intelligence
   • Mission Control status/context/export helpers
2. optional API runtime
   • aiohttp server exposing read-heavy operational surfaces
3. optional on-prem messaging layer
   • mailbox adapter
   • NATS JetStream-backed delivery path
   • policy and flow-control helpers
4. repo-owned scripts
   • smoke/hardening/regression/export/build runners
5. persisted artifacts
   • curated catalog DBs
   • upstream knowledge snapshots
   • logs and summaries

Main Components

• n8n_expert/cli.py
  • primary command surface
• n8n_expert/n8n_api.py
  • live n8n interaction layer
• n8n_expert/catalog_freshness.py
  • catalog age and coverage truth
• n8n_expert/baseline_catalog_refresh.py
  • reproducible baseline refresh and promotion helpers
• n8n_expert/upstream_sync.py
  • upstream release sync and version gap logic
• n8n_expert/upgrade_intelligence.py
  • workflow-aware upgrade analysis
• n8n_expert/context.py
  • workflow context materialization
• n8n_expert/fabric_metadata.py
  • manifest/status export helpers
• n8n_expert/api/routes/*
  • optional REST surfaces
• onprem_mailbox_adapter/*
  • mailbox health/publish/flow-control path
• scripts/*
  • repo-owned verify/export/build/hardening commands

Data Flow

Core workflow/upgrade path

1. CLI or API request enters n8n_expert
2. live n8n calls or local data lookups run
3. results are emitted as:
   • immediate CLI/API responses
   • persisted context/events/log artifacts
   • optional summaries under logs/

Baseline catalog path

1. upstream source is inspected
2. baseline snapshot is built
3. curated base DB and supplemental layer are compared
4. compact summaries and refresh artifacts are written under logs/ and data/upstream/

On-prem delivery path

1. workflow/webhook/adapter receives a dispatch request
2. policy and flow-control logic decide whether to defer/accept/block
3. adapter may publish into JetStream-backed mailbox flow
4. callback/result surfaces report status back into workflow/operator evidence

Internal And External Interfaces

Internal:

• repo scripts to Python package surfaces
• API routes to core runtime helpers
• file contracts under logs/ and data/

External:

• n8n REST API
• optional Mission Control HTTP consumers
• optional event webhook sinks
• optional NATS JetStream mailbox path
• OpenClaw webhook/callback/session environment

Operating Assumptions

• Linux CI runner is the reference platform
• Python CLI/scripts remain the primary operational surface
• API runtime is optional, not the only supported mode
• on-prem delivery is optional and environment-dependent

Role In The Helpifyr Ecosystem

• specialized operator tool for n8n and OpenClaw-adjacent workflows
• not the primary platform backbone
• should expose enough truthful metadata/status for Fabric and wiki aggregation

Expected Role Relative To jhf-fabric

• provide read-only identity, capability, dependency, health/readiness-adjacent, and integration metadata
• allow later discovery/status consumption
• not surrender direct mutation authority for workflow or mailbox operations by default

AGPLv3. Learn more at helpifyr.com.