Skip to main content

Architecture

Documentation Map​

Architecture

Core Positioning​

Helpifyr Spindle is an isolated ERPNext stack that integrates with the existing OpenClaw environment without sharing runtime state. Its Helpifyr role is to own ERP-backed execution, ledger truth, and auditable workflow side effects while adjacent systems handle orchestration or review UX.

Roles​

  • ERPNext / Frappe: source of truth for finance, operations, inventory, assets, and HR records
  • jhf_spindle_core: custom integration and workflow layer inside ERPNext
  • business identity source of truth for Helpifyr users, service accounts, and agent registry metadata
  • OpenClaw: approval and HITL control plane
  • n8n: external orchestration, intake, OCR handoff, notifications, and scheduled syncs
  • Mission-Control / Plane: exception and project tracking surfaces
  • Helpifyr Spindle MCP Gateway: agent-facing MCP layer for finance context and controlled ERP actions

Runtime Boundary​

  • isolated Docker Compose project: Helpifyr Spindle
  • isolated Docker network
  • isolated MariaDB and Redis services
  • dedicated reverse-proxy route: <internal-runtime-redacted> (legacy aliases <internal-runtime-redacted> and <internal-runtime-redacted> remain redirect-only for compatibility)
  • dedicated MCP host port and streamable HTTP endpoint
  • outbound-only integration to existing OpenClaw and n8n endpoints

Main Components​

  • ERPNext / Frappe runtime
  • jhf_spindle_core application layer
  • custom DocTypes for approval, dispatch, resilience, and integration evidence
  • MCP gateway for operator and agent access
  • repo-owned infra scripts for bootstrap, alignment, smoke, release, and metadata export

Main Flows​

Revenue Events​

  1. Paddle or Stripe sends a webhook to ERPNext
  2. jhf_spindle_core validates and records an append-only Integration Event
  3. A normalized Revenue Event is created or deduplicated
  4. Downstream posting and reconciliation stay inside ERPNext workflows

Supplier Intake​

  1. n8n or another intake adapter posts supplier invoice metadata
  2. ERPNext records an append-only Integration Event
  3. Supplier Intake becomes the review-stage record
  4. A later workflow turns that into purchase invoices and approval packets

OpenClaw Approval Bridge​

  1. ERPNext creates an outbound approval request
  2. Approval Packet persists the decision context and callback token hash
  3. OpenClaw runs HITL review outside ERPNext
  4. OpenClaw calls back with the decision
  5. ERPNext verifies the callback token and updates the packet state

MCP Layer​

  1. An agent connects to the Helpifyr Spindle MCP endpoint
  2. MCP tools read finance and integration state directly from Frappe
  3. MCP tools can request approvals or post already-approved staging records
  4. OpenClaw stays the decision plane and ERPNext stays the system of record

Internal And External Interfaces​

Internal:

  • custom DocTypes
  • background workers and scheduler jobs
  • bootstrap, alignment, smoke, and release scripts

External:

  • provider webhooks
  • signed callbacks from OpenClaw and n8n
  • MCP HTTP endpoint
  • webhook dispatch toward jhf-wire

Operating Assumptions​

  • repo and host should stay aligned to avoid runtime drift
  • callback secrets and MCP API keys stay outside git
  • reverse-proxy health is part of the runtime contract
  • external systems may enrich, review, or orchestrate, but must not replace the ledger

Expected Role Toward jhf-fabric​

  • expose repo-owned identity, capability, dependency, lifecycle, and integration metadata
  • allow Fabric to read presence and operator-safe summaries
  • not allow Fabric to bypass approval, posting, or destructive runtime controls

Data Model Additions​

  • Integration Event: append-only ingress and egress event log
  • Revenue Event: normalized payment-provider revenue intake
  • Supplier Intake: pre-accounting invoice staging
  • Approval Packet: OpenClaw-facing approval contract
  • Sync Cursor: replay and connector progress storage
  • Business Identity: business-facing identity source of truth
  • Identity Account Binding: spindle-to-IdP binding record
  • Agent Registry Entry: business-owned agent registry metadata
  • MCP Gateway resources and tools: agent-safe control surface over the existing workflow layer

Localization Baseline​

  • one ERPNext site
  • three companies:
    • Helpifyr Spindle DE
    • Helpifyr Spindle AT
    • Helpifyr Spindle CH
  • retention-profile field on Company
  • company-aware naming-series defaults
  • placeholders for DE e-invoice export and archiving references

License notice: AGPLv3 (GNU Affero General Public License v3.0)
Website: https://helpifyr.com