Architectural truth
How Hyperoru represents what exists, why each relationship exists, confidence, contradictions, and historical change.
Canonical model
Architectural truth is Hyperoru’s evidence-backed belief about a system at a point in time. It is deliberately separate from diagrams, scanner output, model transcripts, and third-party graph schemas.
Core records
Entity
A stable architectural thing: service, API, datastore, queue, identity, cloud resource, deployment unit, pipeline, system, or trust boundary. Entities preserve source-specific identifiers as aliases rather than making any collector’s identifier canonical.
Relationship
A typed edge such as CALLS, READS_FROM, DEPLOYS, OWNS, CONTAINS, or CAN_REACH. Every relationship stores direction, validity window, confidence, contradictions, supersession state, and supporting evidence IDs.
Evidence
An immutable observation that explains why an entity or relationship is believed: file and line, dependency manifest, IaC resource, CI job, cloud asset, API definition, or runtime observation. Evidence records its source type, collection method, source hash, timestamp, and bounded preview.
Context and intent
Context is what Hyperoru can observe: entities, relationships, trust boundaries, source evidence, constraints, and requirements. Intent is a person's decision in response to those facts, including the rationale, accepted trade-offs, and guardrails. Hyperoru does not infer a person's intent from a code pattern or a missing control.
For example, “the API has no authentication middleware” is observed context. “We authenticate only at the gateway to reduce latency, provided all requests pass through that gateway” is intent. A new public route can invalidate that guardrail; its evidence must be reviewed against the ratified decision.
In a workspace, start with Architecture → Map and continue into Truth. Select an entity or relationship to see the evidence, recorded confidence, source families, contradictions, and observation time. Coverage is bounded to the selected snapshot. An unconnected source is unknown, not evidence of a clean system. The map guide walks through the controls and an example.
Open Intent → Record intent to capture the decision against a completed review's truth snapshot. The form records the signed-in owner, supporting observations, the context, proposed choice, rationale, accepted trade-off, alternative, and required guardrail. Saving creates a proposal. An authorized person must explicitly select an option and record a rationale when approving it; the decision retains their identity and approval time. Read recording intent for a concrete example.
Structured criteria can verify an entity, a relationship, or minimum source coverage against newer evidence. A free-text guardrail requires human review and remains inconclusive during automatic verification. See Architecture change intelligence for snapshot comparisons and coverage-aware drift.
The public homepage contains a fictional, local example of these concepts. Its revisions reset on reload and never become workspace approvals.
Confidence is explainable
The interface displays the confidence recorded on an entity or relationship alongside its supporting observations. Read the score with its provenance, observation time, and contradictions. Agreement across sources can support a claim; a stale or conflicting observation can limit what it establishes.
A percentage is not a guarantee and is not a measure of whole-system coverage. A strongly supported code relationship can still belong to a snapshot with no cloud evidence. Open the evidence before relying on the diagram's visual emphasis.
Reconciliation rules
- Normalize source-specific facts before comparison.
- Prefer exact identifiers, then deterministic aliases, then bounded heuristics.
- Preserve both observations when sources disagree.
- Never erase the former relationship; mark its validity window and superseding record.
- Never promote an LLM-only observation to a vulnerability or high-confidence edge.
- Render only from the canonical model, not directly from agent prose.
Temporal behavior
Each audit creates a new observation horizon. Unobserved does not immediately mean deleted: source coverage and freshness determine whether an entity is absent, unknown, or superseded. This lets Hyperoru answer both “what exists now?” and “what changed?” without rewriting history.