Architecture

This page answers the architecture authority question directly: HELM architecture claims must resolve to a source-owned architecture page, ADR, UCS v1.3 section, or implementation source. It is a navigation page for architects, operators, and contributors who need stable, source-backed links before making design, policy, or compliance changes.

This is the first stop for:

• finding the canonical source of architectural truth,
• separating platform conventions from implementation-specific notes,
• and avoiding accidental coupling between docs and non-canonical internal references.

Audience

This page is intended for:

• Architects planning system-level changes
• Protocol and SDK engineers implementing against HELM primitives
• Release managers reviewing boundary changes
• Security and compliance reviewers assessing control-plane placement
• Product operators verifying documentation links used during onboarding and incident response

Outcome

After reading this page, you should be able to:

• identify the authoritative architectural pages for HELM before editing or reviewing PRs,
• trace each architecture claim to a source page or decision record,
• determine whether a change belongs to Kernel documentation or HELM AI Enterprise documentation,
• find conformance references for implementation-level review,
• and use a consistent vocabulary from the canonical lexicon.

Mermaid

flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Kernel["Kernel Semantics"]
        OSS["OSS"]
        Standards["Unified Canonical Standards"]
        RepoMap["Repository Map"]
        Commercial["Commercial"]
        Control["Console & Control Plane Pages"]
        Conformance["Conformance Boundaries"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        ADRs["Architecture Decisions"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Proof["ProofGraph + Receipts"]
    end

    %% Operational Flow Edges
    Kernel --> Proof
    OSS --> Standards
    OSS --> RepoMap
    OSS --> ADRs
    Commercial --> Control
    Commercial --> Conformance
    Kernel --> Standards
    Standards --> Conformance
    Control --> Standards
    Standards --> ADRs
    Conformance --> ADRs

    %% Premium Styling Rules
    style Proof fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style ADRs fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff

flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Kernel["Kernel Semantics"]
        OSS["OSS"]
        Standards["Unified Canonical Standards"]
        RepoMap["Repository Map"]
        Commercial["Commercial"]
        Control["Console & Control Plane Pages"]
        Conformance["Conformance Boundaries"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        ADRs["Architecture Decisions"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Proof["ProofGraph + Receipts"]
    end

    %% Operational Flow Edges
    Kernel --> Proof
    OSS --> Standards
    OSS --> RepoMap
    OSS --> ADRs
    Commercial --> Control
    Commercial --> Conformance
    Kernel --> Standards
    Standards --> Conformance
    Control --> Standards
    Standards --> ADRs
    Conformance --> ADRs

    %% Premium Styling Rules
    style Proof fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style ADRs fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff

Source Truth

• docs/03_ARCHITECTURE.md
• docs/architecture/**
• docs/adrs/**
• docs/HELM_Unified_Canonical_Standard_v1.3.md
• docs/architecture/helm-ai-kernel-vs-commercial.md

What is documented as source-backed architecture

• Architecture Overview — component map, responsibilities, and integration boundaries.
• Repository map source: docs/04_REPO_MAP.md — package boundaries, ownership, and module responsibilities.
• Unified platform source: docs/architecture/UNIFIED_PLATFORM.md — overall platform organization and design philosophy.
• HELM Genesis source: docs/architecture/HELM_GENESIS.md — bootstrap flow and first principles.
• Conformance L3 source: docs/CONFORMANCE_L3.md — high-integrity conformance expectations and evidence posture.
• Lexicon source: docs/16_LEXICON.md — canonical vocabulary for architecture and operations.

HELM AI Kernel vs HELM AI Enterprise boundaries (explicit)

Use docs/architecture/helm-ai-kernel-vs-commercial.md and docs/adrs/adr-001-commercial-boundary.md as the normative boundary definitions. The practical working rule for this site is:

• OSS should be used for baseline kernel, standards, proof semantics, public reference, and reusable specification language.

• HELM AI Enterprise extends operational and product delivery layers (including hosted control-plane surfaces, product-led workflows, and enterprise deployment guidance) but should not redefine OSS semantics.

• If a page documents:

  • contract semantics, or
  • canonical schema-level behavior, or
  • conformance requirements,

  it belongs under OSS source truth unless an explicit Commercial ADR or boundary page overrides it.

• If a page documents pricing, hosted operational behavior, enterprise policy operations, or customer-facing deployment workflows, it belongs to HELM AI Enterprise routing unless OSS explicitly claims ownership.

ADR map for architecture-facing reviews

• ADR index source: docs/adrs/README.md — ordered index for architecture decision context.
• ADR-001 source: docs/adrs/adr-001-commercial-boundary.md — baseline split between OSS and Commercial.
• Additional ADRs under docs/adrs/ — use the index if a specific policy topic requires an ADR-level reference.

If a link is not yet live, treat that as a known gap and flag it in the owning workstream before changing claims.

Troubleshooting

• If an architecture claim appears in code comments or PR descriptions but no matching source page exists, update first with an ADR or OSS canonical page and then rebase the docs route.
• If a page says "Commercial" but points to OSS-standardized semantics, verify whether the claim is a deployment detail or a canonical protocol claim; only the former can remain Commercial-only.
• If repository structure has changed and a canonical link is broken, update this page and the architecture route map together to keep the link graph consistent.
• If reviewers ask for proof, cite this page plus the owning source file in docs/architecture/** rather than internal discussion notes.
• If there is no public page for a newly introduced subsystem, either (a) add the source page through docs authoring first, or (b) classify it as source-only with rationale in the coverage ledger.

Adoption guide

When adding or editing architecture content:

1. Update or confirm the owning source file under docs/architecture/** first.
2. Link the change to the relevant ADR if it affects boundaries, trust assumptions, or protocol interpretation.
3. Reflect the boundary decision in this landing page through the appropriate link entry and keep oss-vs-commercial synchronized.
4. Re-check this page for outdated links and align terminology with docs/architecture/lexicon.