Architecture and Platform Factory Vision

Architecture and Platform Factory vision

This page has two halves, deliberately kept on one page rather than split: what platform-factory actually is today (diagrammed from the code and from docs/, not from aspiration), and where it's headed — the v6 "Graal / Platform Factory" vision recorded in Meine-Graal, turned into diagrams instead of an 1100-line checklist. A status table at the end maps every major Graal v6 section onto what already exists today, so the gap is visible at a glance rather than requiring two documents held in your head at once.

Sources: Reference-Maturity, Reference-Compatibility, OCI-Layout-Architecture, Security-Model, Meine-Graal, Next-Generation-Architecture, Next-Generation-Implementation-Roadmap. Reviewed 2026-08-05 against main; re-verify before trusting a diagram that looks stale, same rule as every other doc in this wiki.

Part 1 — platform-factory today

1.1 System overview

One CLI (platform-factory), four engine groups, no third-party build or virtualization engine in any critical path (Docker/Podman/BuildKit/QEMU are consumers or interop cross-checks, never dependencies of the product's own trust path).

flowchart TB
    CLI["platform-factory CLI\n(build · pipeline · sbom · publish\nverify-release · microvm · doctor)"]

    subgraph CoreOCI["Core OCI engine — v1"]
        Builder["internal/oci.Build\ndeterministic layout construction"]
        Layout["internal/layout\nverification"]
    end

    subgraph Pipeline["Pipeline engine — v2"]
        DAG["internal/pipeline\nAnalyze / Scheduler"]
        Executor["internal/executor\nsandboxed stage runner"]
        Plugin["sdk/plugin*\n5-language RPC protocol"]
    end

    subgraph SupplyChain["Supply chain engine — v3"]
        SBOM["internal/sbom"]
        Provenance["internal/provenance"]
        Signing["internal/signing\nEd25519 / DSSE"]
        Policy["internal/policy"]
        Registry["internal/registry\nnative OCI Distribution client"]
    end

    subgraph MicroVM["MicroVM engine — v4"]
        KVM["internal/hypervisor/kvm\nLinux/amd64"]
        HVF["internal/hypervisor/hvf\nmacOS/arm64"]
        Sandbox["internal/hypervisor/sandbox\nseccomp/namespaces/cgroups"]
        Runtime["cmd/platform-factory-runtime\nOCI runtime facade"]
    end

    subgraph Distributed["Distributed engine — v5"]
        Control["cmd/platform-factory-control-plane"]
        Worker["cmd/platform-factory-worker"]
        Quota["internal/quota"]
        Budget["internal/budget"]
    end

    CLI --> Builder & DAG & SBOM & Registry & KVM & Control
    DAG --> Executor --> Plugin
    Executor -.per-stage.-> Budget
    Builder --> Layout
    SupplyChain --> Registry
    Registry -->|push/pull| ExtReg[("Registry\nGHCR, etc.")]
    Runtime --> KVM & HVF & Sandbox
    Control <-->|mTLS| Worker
    Control --> Quota

    Runtime -->|"OCI runtime = platform-factory-runtime"| Engines[("Podman · Docker\ncontainerd · Kubernetes")]

1.2 Layered package organization

flowchart TB
    subgraph api["api/ — versioned wire contracts"]
        V1["v1 (stable)"]
        V1a["v1alpha1"]
        V1b["v1beta1"]
    end

    subgraph sdk["sdk/ — embeddable client packages"]
        SDKpipeline["sdk/pipeline"]
        SDKmicrovm["sdk/microvm"]
        SDKplugin["sdk/plugin, plugin-python, plugin-js, plugin-csharp"]
    end

    subgraph internal["internal/ — implementation, not importable outside this module"]
        direction LR
        oci["oci · layout · rootfs"]
        pipe["pipeline · executor"]
        sc["registry · signing · sbom\nprovenance · policy"]
        mvm["hypervisor/{kvm,hvf,whpx,sandbox,virtio}\nociruntime · guesttransport"]
        dist["control · quota · budget\nobservability · errors · mtls"]
    end

    subgraph cmd["cmd/ — shipped binaries"]
        main["platform-factory"]
        ocib["oci-builder"]
        cp["platform-factory-control-plane"]
        wk["platform-factory-worker"]
        rt["platform-factory-runtime"]
        inst["platform-factory-installer"]
    end

    api --> sdk --> cmd
    api --> internal
    internal --> cmd
    sdk -.also used directly by user Go programs.-> ext[("third-party Go apps")]

1.3 OCI layout construction (`platform-factory build`)

Deterministic by construction: fixed tar/gzip timestamps, fixed created, content-addressed blobs — identical inputs always produce identical bytes (--rebuild=N --require-identical proves this in CI).

flowchart LR
    Input["executable\n(+ extra files)"] --> Validate["validate:\nregular file, clean paths\nno duplicate labels"]
    Validate --> Tar["deterministic tar\n/app/service, /etc/ssl/certs\n/tmp, /var/tmp (sticky)"]
    Tar --> Gzip["fixed-timestamp gzip"]
    Gzip --> Config["image config\nlinux/amd64 or arm64\nUser 65532:65532"]
    Config --> Manifest["manifest"]
    Manifest --> Index["index.json"]
    Index --> Blobs["blobs/sha256/&lt;digest&gt;\natomic temp-dir + rename"]
    Blobs --> Out[("oci-image/\noci-layout, index.json, blobs/")]

1.4 Pipeline / stage engine (`platform-factory pipeline run`)

flowchart TB
    Doc["pipeline.json\napi/v1alpha1"] --> Analyze["Analyze:\nDAG validation, cycle detection\ncanonical fingerprint"]
    Analyze --> Sched["Scheduler\nparallelism + wall-clock budget"]
    Sched --> S1["stage: sandboxed executor\nLinux namespaces/cgroups\n(falls back to minimal, secret-refusing\nexecutor off Linux)"]
    S1 --> Cache["internal/cache\ncontent-addressed reuse"]
    S1 -->|budget exceeded| Cancel["in-flight stages canceled\nreported budget_exceeded, not canceled"]
    Cache --> Journal["journal.json\nplatform-factory.dev/journal/v1"]
    S1 -.language plugins.-> Ext["external process\nGo/Python/JS/TS/C#\nlength-prefixed JSON-RPC"]

1.5 Supply chain (`platform-factory publish` / `verify-release`)

flowchart LR
    Layout[("oci-image/")] --> Journal[("journal.json")]
    Layout --> SBOM["internal/sbom\nnative inventory"]
    Journal --> Provenance["internal/provenance\nFromJournal"]
    SBOM --> Sign["internal/signing\nEd25519 / DSSE envelope"]
    Provenance --> Sign
    Sign --> PolicyCheck["internal/policy.Evaluate\nagainst evidence + policy.json"]
    PolicyCheck -->|pass| Push["internal/registry\nnative Distribution client\nchunked, resumable CAS"]
    PolicyCheck -->|fail| Refuse["publish refused\n(fail-closed)"]
    Push --> Ext[("Registry\ndigest-pinned")]

1.6 MicroVM runtime (native KVM/HVF, no QEMU on the trust path)

flowchart TB
    Layout[("verified OCI layout")] --> Convert["internal/rootfs.Convert\nverify-before-extract"]
    Convert --> Initramfs["initramfs\n+ pinned guest init"]
    Kernel[("pinned kernel\nsha256-digested")] --> Boot
    Initramfs --> Boot["kvm.RunLinuxWithOptions (Linux/amd64)\nhvf (macOS/arm64)"]
    Boot --> GuestT["guesttransport\nmTLS-authenticated channel"]
    Boot --> Net["TAP + virtio-net\n(linux/amd64 only today)"]
    Boot --> Blk["virtio-blk\n(linux/amd64 only today)"]
    Supervisor["cmd/platform-factory-runtime\n__serve supervisor"] --> Boot
    Supervisor --> Sandbox["internal/hypervisor/sandbox\nno_new_privs always on\ncgroups/cap-bounding-drop\nwhen the host allows it"]
    Supervisor -.OCI runtime verb.-> Engines[("Podman · Docker\ncontainerd")]

1.7 Distributed control plane (`platform-factory-control-plane` / `-worker`)

sequenceDiagram
    participant W as platform-factory-worker
    participant C as platform-factory-control-plane
    W->>C: Register (mTLS cert CN = identity)
    loop every heartbeatInterval
        W->>C: Heartbeat
    end
    loop poll
        W->>C: NextLease (platform/capability/cache-locality aware)
        C-->>W: Lease (or 204, nothing pending)
        W->>W: Execute (sandboxed, budget-tracked)
        W->>C: CompleteLease (workload-identity signed)
    end
    Note over C: Reap loop reclaims leases from<br/>workers whose heartbeat timed out;<br/>re-registration reclaims immediately too
    C->>C: persist to audit log + snapshot

1.8 Maturity, at a glance

Full detail with per-row evidence: Reference-Maturity. Legend: 🟢 Stable · 🔵 Beta · 🟡 Alpha · ⚪ Stub · ⛔ Out of scope.

Capability	v	Status
`build`/`verify`/`inspect`/`diff`/`compose`	v1	🟢
Project config (`.config_image.yaml`)	v1	🔵
Pipeline DAG plan/run/scheduler	v2	🟢
Sandboxed stage executor	v2	🟢 on Linux
Plugin protocol, 5 SDKs	v2	🟢
Registry client — push	v3	🟢
Registry client — pull	v3	🟡 (unwired: no `platform-factory pull`)
Native SBOM/provenance/signing	v3	🟢
`verify-release`	v3	🔵
KVM (Linux/amd64)	v4	🟢
HVF (macOS/arm64)	v4	🔵
KVM (Linux/arm64), WHPX	v4	🟡
`hypervisor/virtio`, TAP networking	v4	🟢 (closed 2026-08-05)
`hypervisor/sandbox` (VMM host process)	v4	🟢 (closed 2026-08-04/05)
Firecracker/Cloud Hypervisor/libkrun/Kata	v4	⛔
Control-plane / worker (mTLS)	v5	🔵
`internal/quota`, `internal/budget`	v5	🔵 wired, opt-in
`internal/observability`, `internal/errors`	v5	🟡 expanding (control, worker now wired)
Separate scheduler binary	v5	🟡 not split out
`platform-factory doctor` (capability diagnostics)	—	🔵 new 2026-08-05

Part 2 — Bridge: reusing the engine, not rebuilding it

Meine-Graal's own "Réutilisation du moteur existant" section states the constraint explicitly: Platform Factory is a new front door, not a second engine. pf doesn't reimplement OCI construction, signing, or MicroVM execution — it drives the same internal/ packages platform-factory already ships, plus two genuinely new capabilities (legacy VM import, and a project-lifecycle state store) that don't exist yet in any form.

flowchart LR
    subgraph pf["pf — new front door"]
        init["pf init"]
        build["pf build"]
        publish["pf publish"]
    end

    subgraph existing["existing platform-factory engine — reused, not duplicated"]
        detect["project detection\n(internal/project)"]
        pipeline["pipeline + OCI builder\n(internal/pipeline, internal/oci)"]
        microvm["MicroVM supervisor\n(cmd/platform-factory-runtime)"]
        proof["SBOM/provenance/signing\n(internal/sbom, signing, provenance)"]
        reg["native Registry client\n(internal/registry)"]
    end

    subgraph net["genuinely new — does not exist today"]
        legacy["legacy VM disk import\n(v6.2 — 0% built)"]
        state["platform-factory.yaml/.lock\nproject state store"]
    end

    init --> detect
    init -.new source type.-> legacy
    init --> state
    build --> pipeline & microvm & proof
    publish --> reg
    publish -.new fan-out.-> Targets[("Podman · Docker · containerd\nKubernetes · Registry")]

Part 3 — The Graal / Platform Factory vision (v6)

Meine-Graal lays out fifteen sub-versions (v6.0–v6.14) plus exit criteria. The full text is the checklist; this is the same plan as a pipeline.

3.1 The whole `pf` pipeline, source to deployed target

flowchart LR
    subgraph Sources
        s1["local repo / dir"]
        s2["Git URL"]
        s3["tar / tar.gz"]
        s4["OCI layout / archive"]
        s5["Docker Save archive"]
        s6["OCI Registry ref"]
        s7["legacy VM disk\n(qcow2, vmdk, vhd(x), raw, iso)"]
    end

    Sources --> init["pf init\necosystem detection OR\nlegacy VM analysis (v6.2/6.3)"]
    init --> plan["transformation plan\ncompatibility report + product manifest"]
    plan --> build["pf build\nOCI · MicroVM · boot bundle\n+ SBOM/provenance/signature"]
    build --> publish["pf publish"]

    publish --> Registry[("OCI Registry")]
    publish --> Podman["Podman\n(container + platform-factory MicroVM)"]
    publish --> DC["Docker / containerd\n(shim, RuntimeClass)"]
    publish --> K8s["Kubernetes\n(manifests, progressive rollout)"]

3.2 v6.2/6.3 — Legacy VM import and transformation plan

The one genuinely new subsystem: read a VM disk read-only, never mount it unconfined, and produce a compatibility report before writing anything.

flowchart TB
    Disk[("VM disk image")] --> FormatDetect["detect format\nRAW · QCOW2 · VMDK · VHD · VHDX · ISO\nheader/size validated before deep read"]
    FormatDetect --> ROpen["open read-only\nconfined parser, bounded offsets/sizes\nno host mount"]
    ROpen --> Partitions["partition table\nMBR · GPT · LVM · encrypted-volume detection"]
    Partitions --> FS["filesystem read\next2/3/4 · XFS · Btrfs · FAT · NTFS(ro)\nfile-count and size bounded"]
    FS --> OSDetect["OS detection\ndistro/version/arch/kernel\nsystemd · SysV · OpenRC · BusyBox\nusers, services, cron, network ports"]
    OSDetect --> Inventory["application inventory\nbinaries, ELF deps, config, secrets flagged"]
    Inventory --> Report["compatibility report\nexecution mode: container-viable?\nMicroVM-viable? conversion blockers?"]
    Report --> Manifest["product manifest\ninput to pf build"]

3.3 v6.7–v6.9 — Multi-target deployment fan-out

flowchart TB
    Artifact[("build output:\nOCI image + MicroVM boot bundle\n+ SBOM/provenance/signature")]

    Artifact --> Podman1["Podman: standard container"]
    Artifact --> Podman2["Podman: platform-factory MicroVM\n(same supervisor as today)"]
    Artifact --> Docker["Docker\n(opt-in runtime registration)"]
    Artifact --> Containerd["containerd shim\nio.containerd.platform-factory.v1"]
    Containerd --> K8sManifests["Kubernetes manifest generation\nRuntimeClass, progressive rollout"]
    K8sManifests --> Lifecycle["lifecycle: create/start/logs/stop/delete\nconsistent across all four targets\n(same identity, same MicroVM state)"]

3.4 v6.12 — `pf doctor` and observability

Notable: this section is already partially built — platform-factory doctor, shipped 2026-08-05, is a direct implementation of exactly this Graal item, just under the current CLI name.

flowchart LR
    doctor["pf doctor / platform-factory doctor"] --> tools["external tool presence\ngit, docker, podman, containerd, kubectl"]
    doctor --> hv["native hypervisor availability\n(hypervisor.ProbeNative)"]
    doctor --> sb["VMM sandbox capability\n(sandbox.ProbeSandbox:\nnamespaces, cgroups, cap-bounding-drop)"]
    doctor -.Graal-only, not yet built.-> rt["runtime/cluster state\n(registered OCI runtimes,\nlive containerd/K8s state)"]
    doctor -.Graal-only, not yet built.-> reg["Registry connectivity\n/ auth diagnostic"]

3.5 Recommended execution order

Meine-Graal's own priority ordering — this is the plan, not a suggestion this page is inventing:

flowchart LR
    P0["P0 — Close v4\n(this repo's current focus)"] --> P1["P1 — pf facade\ninit/build/publish over\nthe existing engine"]
    P1 --> P2["P2 — legacy import\nas inventory only\n(no conversion yet)"]
    P2 --> P3["P3 — legacy → OCI\nconversion"]
    P3 --> P4["P4 — multi-target\ndeployment"]
    P4 --> P5["P5 — distributed\nproduction"]

Part 4 — Status: what's reusable today vs. genuinely new work

Graal v6 section	Today's equivalent	Gap
v6.0 CLI foundation, identity/distribution	`platform-factory` binary, `--json`, exit codes, completion	Rename/rebrand only — engine is there
v6.1 `pf init` — ecosystem detection	`internal/project` detection (Go/Node/Python/Java/.NET)	Broaden language list; add multi-source support
v6.1 `pf init` — config migration	`platform-factory project migrate` (`.config_image.yaml`)	Extend to `platform-factory.yaml` schema
v6.2 Legacy VM import	nothing	100% new: disk formats, partitions, filesystems, OS detection
v6.3 Transformation plan	`platform-factory pipeline plan` (DAG only)	New: compatibility report, execution-mode classification
v6.4 `pf build` — OCI/pipeline	`internal/oci.Build`, `internal/pipeline`	Wire, don't rebuild
v6.4 `pf build` — MicroVM	`cmd/platform-factory-runtime`, KVM/HVF	Wire, don't rebuild
v6.5/6.6 `pf publish` — Registry	`internal/registry` (push 🟢, pull 🟡)	Wire; finish the pull path
v6.7 Podman deployment	already the primary supported path	None
v6.8 Docker/containerd	shim + opt-in runtime registration exist	None
v6.9 Kubernetes	`plugins/containerd`, `RuntimeClass`, kind-tested	Progressive-rollout tooling is new
v6.10 Network/storage (MicroVM)	TAP + virtio-net/blk (linux/amd64)	Extend beyond linux/amd64; storage beyond one virtio-blk device
v6.11 Guest agent	`guesttransport` (mTLS channel exists)	Broaden the agent's own command surface
v6.12 Observability / `pf doctor`	`platform-factory doctor`, structured logs (control-plane only)	Runtime/cluster/Registry diagnostics; observability end-to-end
v6.13 Distributed deployment	control-plane/worker (v5, Beta)	Already the closest-to-done Graal section
v6.14 Security/stabilization, external audit	Threat Model v2.0, no third-party review yet	Same gap the v1-v5 roadmap already tracks

platform-factory

Home

todo

Core

CI/CD

Running an image

Operating

Architecture and Platform Factory Vision

Architecture and Platform Factory vision

Part 1 — platform-factory today

1.1 System overview

1.2 Layered package organization

1.3 OCI layout construction (platform-factory build)

1.4 Pipeline / stage engine (platform-factory pipeline run)

1.5 Supply chain (platform-factory publish / verify-release)

1.6 MicroVM runtime (native KVM/HVF, no QEMU on the trust path)

1.7 Distributed control plane (platform-factory-control-plane / -worker)

1.8 Maturity, at a glance

Part 2 — Bridge: reusing the engine, not rebuilding it

Part 3 — The Graal / Platform Factory vision (v6)

3.1 The whole pf pipeline, source to deployed target

3.2 v6.2/6.3 — Legacy VM import and transformation plan

3.3 v6.7–v6.9 — Multi-target deployment fan-out

3.4 v6.12 — pf doctor and observability

3.5 Recommended execution order

Part 4 — Status: what's reusable today vs. genuinely new work

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

1.3 OCI layout construction (`platform-factory build`)

1.4 Pipeline / stage engine (`platform-factory pipeline run`)

1.5 Supply chain (`platform-factory publish` / `verify-release`)

1.7 Distributed control plane (`platform-factory-control-plane` / `-worker`)

3.1 The whole `pf` pipeline, source to deployed target

3.4 v6.12 — `pf doctor` and observability