Skip to main content

System Model

Use this page when you need the high-level mental model for how Helpifyr publishes truth, delegates ownership, and separates docs, runtime, and product responsibilities.

When to use this page​

  • You are new to the stack and need the shortest correct architecture explanation.
  • You need to understand what Fabric owns versus what product repos and environments own.
  • You need a public-safe explanation before deeper operator or implementation work.

Prerequisites​

  • You can read Platform Truth and product pages under /products.
  • You understand that public docs describe contracts and safe workflows, not secret material.

Core model​

Helpifyr is a governed control plane around repo truth, contract truth, and runtime verification.

It is not a single monolith that owns every downstream mutation directly. Instead, it coordinates:

  • repo-owned source truth
  • Fabric-published contracts and projections
  • product-specific runtime and integration owners
  • human review and signoff where required

Architecture / Flow​

Step-by-step explanation​

1. Owner repos stay the first source of truth​

Canonical files, contracts, manifests, and product docs begin in owner repos. Public docs should point back to that ownership instead of inventing detached truth.

2. Fabric publishes shared truth​

Fabric turns repo truth into common surfaces such as:

GET /api/v1/contracts/registry
GET /api/v1/contracts/drift
GET /api/v1/platform/projection-catalog
GET /api/v1/platform/version-truth

These endpoints provide a stable readback layer for operators, docs materialization, and guarded automation.

3. jhf-docs materializes reviewed public documentation​

jhf-docs is the reviewable workspace for public docs artifacts. It should:

  • materialize owner-approved source truth
  • add repo-owned public-safe longform guidance where needed
  • avoid creating shadow contracts or contradictory reference content

4. jhf-docs publishes the reviewed public docs artifact​

The canonical docs site should reflect reviewed mainline truth, not ad hoc local content. This is why docs provenance and runtime readback matter. Main-site shell links or compatibility aliases may still be consumed through jhf-web, but they must not be described as the canonical publisher path.

5. Humans stay in the loop for risky transitions​

Helpifyr supports automation, but review gates remain important for:

  • rollout and recovery actions
  • security-sensitive changes
  • signoff and residual-risk decisions

Verification​

You have the system model right when you can answer:

  1. which repo owns the canonical source
  2. which Fabric route publishes shared truth for that source
  3. whether the next action belongs in docs, runtime operations, or a downstream owner repo

Common failure modes​

Treating public docs as the canonical source​

Problem:

  • changes are made in the materialized layer instead of the owner layer.

Better path:

  • update the owner repo or explicitly repo-owned docs override lane

Treating Fabric as the owner of every downstream mutation​

Problem:

  • automation boundaries become unsafe and misleading.

Better path:

  • keep owner repos and owner runtimes explicit

Source Truth​

Next paths​