Zum Hauptinhalt springen

Event Modeling

Use this page when you need a public-safe but operationally useful explanation of how Helpifyr catalogs event families, dependency relationships, and projection truth after the write-truth model is already clear.

When to use this page​

  • You are tracing a flow across services or repos.
  • You need to map an event family to an operator-facing projection.
  • You need the human-readable companion to the event-modeling routes and dependency graph surfaces.

Prerequisites​

Architecture / Flow​

Step-by-step procedure​

1. Start from the published event-modeling routes​

Illustrative reads:

GET /api/v1/event-modeling/catalog
GET /api/v1/event-modeling/dependency-graph

These routes are the machine-readable source for:

  • event families
  • dependency relationships
  • flow explainability

They are not the append-only event-store truth. That sourcing boundary is described on Event Sourcing.

2. Pair the model with projection and readiness truth​

Event explanations become operationally useful only when paired with:

GET /api/v1/platform/projection-catalog
GET /api/v1/observability/readiness

3. Use Mermaid for flow explanation, not just ornament​

Event, dependency, and upgrade sequences should be diagrammed when they clarify:

  • upstream trigger
  • intermediate projection or state update
  • downstream operator impact

4. Keep event docs fail-closed​

If the source event model is incomplete, the docs should point to the missing or canonical source rather than invent a flow that looks plausible.

Verification​

This page is being applied correctly when:

  1. the event family is tied to a published route or artifact
  2. the diagram and text agree on the flow
  3. the reader can connect the event model to a real verification path

Common failure modes​

Describing a flow only as prose​

Problem:

  • dependency and order mistakes become hard to spot.

Better path:

  • pair prose with Mermaid and route readback

Treating an inferred flow as canonical​

Problem:

  • docs become more confident than the source truth.

Better path:

  • fail closed or cite the exact route family

Using event modeling as a substitute for event sourcing​

Problem:

  • readers understand route catalogs and dependency graphs but still miss replay, append-only, or idempotency constraints.

Better path:

  • anchor the write-truth model in Event Sourcing first, then use event-modeling routes to explain family and dependency relationships

Source Truth​

Next paths​