Skip to main content

Overview

What This Repository Is​

Helpifyr Spindle is the repo-owned ERP and operations backbone for the OpenClaw/Helpifyr environment. It extends ERPNext/Frappe with finance, intake, approval, dispatch, MCP, compliance, and verification surfaces.

When To Use Spindle​

Use Spindle when a workflow needs canonical business truth, ERP-backed execution, or auditable finance and operations evidence. It is the module to consult when business records, approval-linked business actions, dispatch-tracked documents, or ERP-owned identity/business-role facts must stay authoritative.

What Spindle Owns​

  • Company bootstrap and reconcile truth for ERP-scoped company setup, fiscal-year posture, admitted W1 company-profile truth, and governed business defaults across quickstart, full, add-company, and reconcile-company-profile modes.
  • ERP and business-object truth for the admitted Spindle domain.
  • Managed config truth for company-scoped reporting, numbering, approval, and statutory-output posture that lives in ERP business state.
  • Reporting/statutory/output truth for repo-owned close, approval, dispatch, and compliance flows.
  • Metadata and references for final dossiers/documents whose immutable file truth lives in Loom.
  • Business-side execution evidence and dispatch/approval callback reconciliation.
  • Repo-owned MCP operator surfaces for Spindle-owned business workflows.
  • Business-facing identity and posture projections consumed by other Helpifyr modules.

What Spindle Does Not Own​

  • Central OIDC/session authority or delegated-login truth.
  • Fabric registry, governance, or cross-stack admission ownership.
  • External carrier, provider, or shared-host runtime ownership outside repo-defined boundaries.
  • Final dossier/document archive truth outside metadata and refs.
  • Authority/advisor delivery transport or submission readback owned by jhf-wire.
  • Lantern-local or Pattern-local mutation/progress/remediation truth.
  • Publisher truth for public docs materialization.

Main Building Blocks​

  • apps/jhf_spindle_core
    • custom Frappe app with services, APIs, DocTypes, and MCP support
  • infra/compose
    • canonical Docker Compose runtime
  • infra/scripts
    • bootstrap, align, smoke, release, and metadata helper scripts
  • docs/
    • operator, architecture, release, integration, and Fabric-facing repo docs

Repo Category​

  • category: service
  • secondary classification: standalone ERP-backed tool

Current Lifecycle​

  • lifecycle: active
  • maturity: pilot
  • source of truth: Gitea main

Fabric Readiness​

This repo is now prepared for later Fabric modeling through:

  • fabric-manifest.json
  • docs/FABRIC_TOOL_PROFILE.md
  • docs/FABRIC_CONTRACT.md

It is not yet directly integrated into jhf-fabric.

How To Verify The Current Repo-Owned State​

  • py infra/scripts/check_markdown_compliance.py
  • py infra/scripts/check_compatibility_contracts.py --check
  • py infra/scripts/export_fabric_metadata.py --check
  • py <local-workspace-redacted>/helpifyr-fabric/scripts/docs/validate_repo_docs_skeleton.py --repo <local-workspace-redacted>/_worktrees/jhf-spindle/420-wave6-public-docs-source-curation

These checks validate the public-safe source docs, metadata consistency, and the repo's declared documentation skeleton without claiming that every optional runtime lane is live.

Where To Start​

  • product entrypoint: README.md
  • install/bootstrap: docs/INSTALL.md
  • runtime/config map: docs/CONFIGURATION.md
  • operations: docs/RUNBOOK.md
  • fast fault isolation: docs/TROUBLESHOOTING.md
  • integrations: docs/INTEGRATIONS.md
  • security boundaries: docs/SECURITY.md
  • release/update logic: CHANGELOG.md, docs/RELEASE_NOTES.md, RELEASE_POLICY.md

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