Forgeyard System Architecture Wiki

Welcome to the official Forgeyard Architecture Wiki. This knowledge base contains the complete architectural specifications, execution models, protocol contracts, domain abstractions, and toolchain definitions for Forgeyard.

Forgeyard is a next-generation, high-performance, reproducible, and hermetic CI/CD and software delivery platform engineered as a modular Rust workspace.

High-Level System Topology

The diagram below illustrates the architectural layers and inter-subsystem data flows across the Forgeyard platform:

flowchart TB
    subgraph ClientLayer["User & Interface Layer"]
        CLI["Forgeyard CLI"]
        GUI["Dioxus UI / GUI (Web & Desktop)"]
        SCMHook["SCM Webhooks (GitHub / GitLab / Gitea)"]
        IDE["Dev Workspace & IDE Bridge"]
    end

    subgraph GatewayLayer["API & Control Ingress"]
        AxumGW["Axum API Gateway (REST / gRPC / WebSocket)"]
        AuthN["Identity & Token Verification"]
        PolicyEngine["Policy & RBAC/ABAC Evaluator"]
    end

    subgraph CorePlane["Core Orchestration & Planning Plane"]
        IRPlanner["Pipeline IR Parser & DAG Planner"]
        StateMachine["Run & Job State Machine"]
        Scheduler["Distributed Scheduler & Resource Matcher"]
        Reconciliation["Event Bus & State Reconciliation"]
        LockCoord["Distributed Lock & Idempotency Engine"]
    end

    subgraph StoragePlane["Storage & Content-Addressable Plane"]
        MetaDB["Metadata & State Database"]
        CAS["CAS (Content-Addressable Storage) Engine"]
        RemoteCache["Remote Build Cache & Acceleration"]
        ArtifactReg["Artifact Registry & OCI Distribution"]
    end

    subgraph ExecutionPlane["Execution & Runner Plane"]
        QUIC["QUIC Secure Internal Transport"]
        RunnerAgent["Runner Daemon Agent"]
        SandboxMicroVM["MicroVM / Container Sandbox Executor"]
        DeviceLab["Hardware & Device Testbed"]
        FleetAutoscaler["Runner Fleet Autoscaler"]
    end

    subgraph SecurityPlane["Security, Trust & Supply Chain"]
        SecretsVault["Secrets Vault & Zero-Trust Ephemeral Creds"]
        SBOMSign["SBOM & Cryptographic Provenance (Cosign/In-Toto)"]
        AuditCompliance["Audit Log & Compliance Governance"]
    end

    CLI --> AxumGW
    GUI --> AxumGW
    SCMHook --> AxumGW
    IDE --> AxumGW

    AxumGW --> AuthN --> PolicyEngine --> IRPlanner
    IRPlanner --> StateMachine --> Scheduler
    Scheduler --> Reconciliation
    StateMachine --> LockCoord

    StateMachine --> MetaDB
    IRPlanner --> CAS
    Scheduler --> QUIC

    QUIC --> RunnerAgent
    RunnerAgent --> SandboxMicroVM
    RunnerAgent --> DeviceLab
    FleetAutoscaler --> RunnerAgent

    SandboxMicroVM --> RemoteCache
    SandboxMicroVM --> CAS
    SandboxMicroVM --> ArtifactReg

    SandboxMicroVM --> SecretsVault
    SandboxMicroVM --> SBOMSign
    Reconciliation --> AuditCompliance

Architectural Taxonomy (82 Specifications)

The 82 system architecture specifications are organized into 10 cohesive architectural domains:

1. Core Foundations & Source Domain

Foundational domain models, typed identities, invariants, VCS neutrality, and Change Proposals.

2. Storage, CAS & Data Plane

Metadata persistence, Content-Addressable Storage (CAS), remote caching, lifecycle policies, and schema evolution.

3. Pipeline Engine, IR, State Machine & Scheduling

Intermediate Representation (IR), DAG evaluation, run/job state transitions, distributed scheduling, concurrency locks, and checkpointing.

4. Runners, Sandboxing, Transport & Fleet Orchestration

Runner daemon agents, sandbox execution environments (microVM/container/chroot), internal QUIC transport, device testbeds, autoscaling, and zero-trust tunneling.

5. Security, Policy, Secrets & Supply Chain

Fine-grained ABAC/RBAC authorization, secrets vaults, cryptographic provenance/SBOM signing, multi-tenancy quotas, audit compliance, and threat mitigation.

6. Packaging, Releases, Deployment & Delivery

Hermetic functional packaging, reproducible distribution, deployment orchestration, automated release channels, progressive delivery, and artifact promotion.

7. Observability, Diagnostics, Testing & Quality

Telemetry & doctor diagnostics, operational search analytics, quality gates & flaky test intelligence, performance benchmarking, static analysis, failure bisecting, SLO error budgets, and incident postmortems.

8. API, UI, DevEx & Service Portal

Axum HTTP/gRPC gateway, Dioxus Web/Desktop GUI, local CLI / workstation ergonomics, golden path workflow templates, developer service catalog, API/ABI compatibility, and cloud workspace orchestration.

9. Distributed Coordination, Federation & Operations

SCM provider integrations, Raft consensus high availability, Remote Build Execution (RBE) interop, WASM plugin extensions, disaster recovery, air-gapped self-hosting, human approval workflows, subscription licensing, monorepo graph analysis, dependency mirroring, configuration drift detection, merge queues, and AI-assisted CI optimization.

10. Ecosystems & Language Toolchains

Targeted architecture specifications for hermetic multi-language compilation, dependency management, toolchain isolation, and test runners.

Global Design Principles

1. Strict Type Safety & Strong Invariants: All identities (runs, jobs, artifacts, runners, nodes) are strongly typed UUID/ULID primitives.
2. Hermeticity & Reproducibility: Every build and test step runs in content-addressed, hermetic sandboxes with explicit inputs and outputs.
3. Transport Efficiency: Control plane and runner nodes communicate via multiplexed QUIC streams with mutual TLS.
4. VCS Neutrality: Universal Git/Jujutsu/Mercurial/Pijul source abstraction layer decoupling Forgeyard from any single SCM provider.
5. Supply Chain Integrity: Built-in cryptographic provenance attestation, SBOM generation, and SLSA Level 3+ compliance by default.

This Wiki is automatically synchronized from the sys-arch/ directory in the Forgeyard repository.