Skip to main content

Architecture

Documentation Map​

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.