Skip to main content

jhf-wire Project Plan

Documentation Map​

jhf-wire Project Plan

Summary​

jhf-wire is the standalone connector repository for Helpifyr Spindle provider integrations. It owns workflow orchestration, provider-side submission logic, callback delivery, and isolated deployment, while Helpifyr Spindle remains the source of business documents and dispatch requests.

Scope​

In scope:

  • four n8n workflow exports
  • ERiC microservice for ELSTER UStVA submission
  • isolated production stack definition
  • isolated local and CI test stack
  • interface contract for Helpifyr Spindle handoff
  • operational, deployment, and failure-mode documentation

Out of scope:

  • changes inside the Helpifyr Spindle application repository
  • mutation of unrelated containers or stacks on the host
  • heavy dedicated monitoring stack for v1

Key Deliverables​

  • n8n-workflows/jhf-spindle-sepa-submit.workflow.json
  • n8n-workflows/jhf-spindle-bank-sync.workflow.json
  • n8n-workflows/jhf-spindle-xrechnung-dispatch.workflow.json
  • n8n-workflows/jhf-spindle-elster-submit.workflow.json
  • infra/eric-service/
  • infra/docker/docker-compose.stack.yml
  • infra/docker/docker-compose.test.yml
  • tests/test_integration_saas_connectors.py
  • full docs pack under docs/

Architecture​

Helpifyr Spindle dispatch -> n8n workflow -> provider -> signed callback -> Helpifyr Spindle

Provider mapping:

  • SEPA -> finAPI payments
  • Bank sync -> finAPI transactions -> Helpifyr Spindle MCP import
  • XRechnung -> Storecove document submission
  • ELSTER -> ERiC wrapper -> callback

Design Defaults​

  • Git is the only source of truth for workflow definitions
  • n8n is a deployment target, not the authority
  • dispatch_job is the idempotency anchor across retries and callbacks
  • provider failures should yield explicit error callbacks whenever enough context exists
  • direct edits in the n8n UI are overwritten by the next repository-driven import
  • all production services stay inside one stack named jhf-wire

Acceptance Criteria​

  • repo contains complete docs, workflows, test stack, prod stack, scripts, and tests
  • workflows are stable and reviewable in Git
  • local test stack can boot without touching any existing host stack
  • ERiC wrapper exposes /health and /submit/ustva
  • integration tests cover happy path and key failure-path expectations
  • deployment runbook is specific enough to execute safely on <internal-runtime-redacted>
  • operator checks distinguish stack health from true external-submission readiness
  • pending external credentials are surfaced explicitly instead of being mistaken for a healthy-ready state

License: AGPLv3 Project website: https://helpifyr.com