Skip to main content

Integration Ownership Model

Use this page when you need to know which repo or runtime owns an integration behavior before you implement or troubleshoot it.

When to use this page​

  • You are deciding where a change belongs.
  • You need to avoid fixing an integration symptom in the wrong repo.
  • You need a public-safe handoff model for Helpifyr-connected systems.

Prerequisites​

  • You have read System Model.
  • You know which product or runtime is involved.

Architecture / Flow​

flowchart LR
    A["Integration question"] --> B["Find canonical owner repo"]
    B --> C["Find Fabric shared truth surface"]
    C --> D["Find docs or runtime consumer"]
    D --> E["Apply change in owner lane"]

Step-by-step procedure​

1. Start with the owner question​

Ask:

  • Which repo defines the contract?
  • Which runtime exposes the live behavior?
  • Which docs repo only materializes or publishes the reviewed result?

2. Apply the standard ownership split​

  • helpifyr-fabric
    • owns shared control-plane routes, contracts, projections, and public docs-platform truth
  • jhf-docs
    • owns reviewed public-docs materialization and repo-owned safe overrides
  • jhf-web
    • owns the live site publishing and deployment of the reviewed artifact
  • downstream product repos
    • own product-specific runtime behavior and local contracts that Fabric consumes or summarizes

3. Use Fabric as the shared readback layer​

Illustrative routes:

GET /api/v1/contracts/registry
GET /api/v1/platform/projection-catalog
GET /api/v1/tools/runtime-status
GET /api/v1/docs/platform

These routes tell you what Fabric currently believes and publishes, but they do not automatically make Fabric the mutation owner for every downstream behavior.

4. Send the fix to the true owner lane​

Examples:

  • stale public page structure:
    • likely jhf-docs or jhf-web
  • missing or wrong shared route documentation:
    • likely helpifyr-fabric
  • product-specific runtime mismatch:
    • likely the downstream owner repo or environment

Verification​

Ownership is classified correctly when:

  1. the canonical repo is explicit
  2. the readback route is explicit
  3. the next mutation does not happen in a non-owner layer

Common failure modes​

Fixing a shared-truth problem only in the published site​

Problem:

  • the symptom disappears briefly but source truth stays wrong.

Better path:

  • fix the source or the materializer that owns the publication

Treating jhf-docs as the owner of product runtime behavior​

Problem:

  • documentation work becomes a false runtime fix.

Better path:

  • use jhf-docs for reviewed public content, not product runtime ownership

Source Truth​

Next paths​