ARCHITECTURE_DIAGRAMS

Q-Trust Plane — Architecture Diagram Pack
Document: Visual Architecture Reference
Version: 1.0
Format: Mermaid (GitHub/GitLab compatible)

This document provides visual representations of Q-Trust Plane’s architecture, flows, trust boundaries, and cryptographic governance model.

Diagram 1 — System Overview (Control Plane vs Execution Plane)

flowchart LR
  subgraph ControlPlane["Q-Trust Control Plane"]
    API[API Gateway]
    ID[Identity Verifier]
    AT[Attestation Verifier]
    PE[Policy Engine (QPL)]
    GI[Grant Issuer]
    EL[Evidence Ledger]
    MB[Merkle Batcher]
    AN[On-Chain Anchorer]
  end

  subgraph ExecutionPlane["Execution Plane (Agents / PEPs)"]
    CIa[CI Agent]
    TFa[Terraform Agent]
    K8a[K8s Admission Agent]
    W3a[Web3 Agent]
    MLa[MLOps Agent]
  end

  subgraph External["External Systems"]
    OIDC[OIDC Issuers]
    REG[Artifact Registry]
    K8S[Kubernetes]
    TF[Terraform]
    CH[(Blockchains)]
    AA[(AuditAnchor)]
  end

  ExecutionPlane --> API
  API --> ID --> PE
  API --> AT --> PE
  PE --> GI --> API

  ExecutionPlane -->|Evidence| API
  API --> EL --> MB --> AN --> CH --> AA

Diagram 2 — Authorization Decision Flow (PDP)

sequenceDiagram
  participant Agent
  participant API
  participant Identity
  participant Attestation
  participant Policy
  participant Grant

  Agent->>API: Authorization Request
  API->>Identity: Verify identity (OIDC/workload)
  API->>Attestation: Verify attestations
  Identity-->>API: Subject fingerprint
  Attestation-->>API: Attestation verdict
  API->>Policy: Evaluate QPL (deny-wins)
  Policy-->>API: Allow/Deny + obligations
  API->>Grant: Issue grant (TTL + nonce)
  Grant-->>API: Signed grant
  API-->>Agent: Grant or denial reason

Diagram 3 — Grant Lifecycle (Capability Model)

stateDiagram-v2
  [*] --> Requested
  Requested --> Evaluated
  Evaluated --> Denied
  Evaluated --> Issued
  Issued --> Consumed
  Consumed --> Expired
  Issued --> Expired

  note right of Issued
    Grant properties:
    - TTL (seconds)
    - Single-use
    - Context-bound
    - Hybrid-signed
  end note

Diagram 4 — Evidence Chain & On-Chain Anchoring

flowchart TB
  E1[Evidence Event N]
  E2[Evidence Event N+1]
  E3[Evidence Event N+2]

  E1 -->|hash| E2 -->|hash| E3

  E1 --> L1[Leaf Hash]
  E2 --> L2[Leaf Hash]
  E3 --> L3[Leaf Hash]

  subgraph Merkle["Merkle Tree (Epoch)"]
    L1 --> R
    L2 --> R
    L3 --> R
  end

  R --> AA[(AuditAnchor Contract)]

Diagram 5 — CI/CD + Web3 Deployment Flow

sequenceDiagram
  participant Dev
  participant CI
  participant Agent
  participant QTrust
  participant Chain

  Dev->>CI: Push signed tag
  CI->>Agent: Start release pipeline
  Agent->>QTrust: Request deploy authorization
  QTrust-->>Agent: Grant (TTL 90s)
  Agent->>Chain: Deploy contract
  Agent->>QTrust: Submit evidence (tx hash)
  QTrust->>Chain: Anchor Merkle root

Diagram 6 — Terraform Apply Governance (IaC)

flowchart LR
  TFPlan[terraform plan]
  TFSign[Signed Plan]
  Agent[Terraform Agent]
  QTrust[Q-Trust Plane]
  Prod[Production Infra]

  TFPlan --> TFSign
  TFSign --> Agent
  Agent --> QTrust
  QTrust -->|Grant| Agent
  Agent -->|apply| Prod
  Agent -->|evidence| QTrust

Diagram 7 — Kubernetes Admission Control

flowchart TB
  Pod[Pod Spec]
  K8S[K8s API Server]
  Agent[K8s Admission Agent]
  QTrust[Q-Trust Plane]

  Pod --> K8S
  K8S --> Agent
  Agent --> QTrust
  QTrust -->|Allow/Deny| Agent
  Agent --> K8S

Diagram 8 — Bridge Signer Rotation (Critical Web3 Action)

sequenceDiagram
  participant Operator
  participant Agent
  participant QTrust
  participant Chain

  Operator->>Agent: Initiate signer rotation
  Agent->>QTrust: Request authorization
  QTrust-->>Agent: Grant (TTL 45s)
  Agent->>Chain: Rotate signers
  Agent->>QTrust: Evidence (new signer hash)
  QTrust->>Chain: Anchor Merkle root

Diagram 9 — Trust Boundaries

flowchart LR
  subgraph Untrusted
    CI[CI Runners]
    Users[User Workstations]
    Nodes[Cluster Nodes]
  end

  subgraph SemiTrusted
    OIDC[OIDC Issuers]
    REG[Registries]
  end

  subgraph Trusted
    QTrust[Q-Trust Control Plane]
    Vault[Key Vault / HSM]
    Chain[(Blockchain Integrity)]
  end

  Untrusted --> SemiTrusted
  SemiTrusted --> Trusted

Diagram 10 — External Audit Verification

sequenceDiagram
  participant Auditor
  participant QTrust
  participant Chain

  Auditor->>QTrust: Request audit proof
  QTrust-->>Auditor: Leaf + Merkle proof + txHash
  Auditor->>Chain: Verify root existence
  Auditor->>Auditor: Verify inclusion proof

Diagram 11 — Multi-Tenant Isolation

flowchart TB
  subgraph TenantA
    PA[Policies]
    KA[Keys]
    EA[Evidence]
  end

  subgraph TenantB
    PB[Policies]
    KB[Keys]
    EB[Evidence]
  end

  TenantA --- QTrust
  TenantB --- QTrust

Diagram 12 — High-Risk Action Safety Envelope

flowchart LR
  Action[Critical Action Request]
  Policy[Policy Check]
  Grant[Grant Issuance]
  Exec[Execution]
  Evidence[Evidence]
  Anchor[On-Chain Anchor]

  Action --> Policy --> Grant --> Exec --> Evidence --> Anchor

Notes

• All diagrams are source-of-truth aligned with:

  • README.md
  • ARCHITECTURE.md
  • QPL-SPEC.md
  • THREAT-MODEL.md

• Mermaid syntax is compatible with GitHub/GitLab rendering.

• Diagrams are intentionally minimal but semantically dense.

If you can draw it, you can govern it. If you can govern it, you can prove it.