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​

flowchart LR
    A["Owner repos"] --> B["Fabric contracts and projections"]
    B --> C["Materialized docs and reviewed artifacts"]
    B --> D["Runtime readiness and health surfaces"]
    B --> E["Operator and automation decisions"]
    E --> F["Downstream owner repos or runtimes"]

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-web publishes the reviewed artifact​

The live docs site should reflect reviewed mainline truth, not ad hoc local content. This is why docs provenance and runtime readback matter.

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​