Skip to content

Architecture Packet

sergio velderrain edited this page Nov 6, 2026 · 24 revisions

Architecture Packet

Satisfies Software-Requirements-Specification (VITechnologies/projectbuddy#10): architecture description with all 4 required views (Context, Container, Component, Deployment), named stakeholders and concerns, and retained decision rationale.

Overview

  • System: VITechnologies/projectbuddy
  • Purpose: a public, project-agnostic engine for provisioning self-hosted build/test infrastructure and running native SBOM reporting pipelines for downstream consumer repositories.
  • Scope: VM provisioning (Windows+LabVIEW, Ubuntu+LabVIEW), native and containerized SBOM build/report pipelines, project registration (add-project.yml), and (new) human-escalation and repo-onboarding tooling.

Stakeholders And Concerns

Stakeholder Concern Viewpoint
Product (operator/fork owner) The engine must never assume one fork's private identity/infrastructure Consumption model, Context View
Engineering (agent/contributor) Changes must be traceable to a requirement and reviewable before merge Software-Requirements-Specification, Component View
Operations (consumer repo maintainer) Upgrades must be deliberate, never silent/floating Context View, Deployment View
Security Tokens/secrets must be least-privilege and never leak across repos Component View (Enable-RepoIssueTracking.ps1, standards-compliance-recheck.yml's persist-credentials: false fix)

Context View

  • External actors: the fork owner (operator) dispatching workflows and reviewing escalations; contributors opening PRs against feature/* branches.
  • Upstream systems: svelderrainruiz/repo-standards-review (the authoritative compliance standard this repo is assessed against); GitHub itself (Actions, Issues, Releases, Wiki).
  • Downstream systems: consumer repositories (e.g. VITechnologies/SandboxSBOMReporting) that pin this engine's reusable workflows/scripts at a specific release SHA; self-hosted runner VMs (Windows+LabVIEW, Ubuntu+LabVIEW) this engine provisions; the NI LabVIEW/VIPM toolchain those VMs run.

Container View

Container Responsibility Technology
VM provisioning (vm/windows-labview/, vm/ubuntu-labview/) Create, register, and track self-hosted build/test VMs as GitHub Actions runners PowerShell, Bash, Python, VirtualBox, NSIS
Native SBOM pipeline (root Run-*.ps1/.sh, Build-Sbom.ps1, internal/) Run the LabVIEW build-and-report pipeline directly on a self-hosted runner PowerShell, Python
Containerized SBOM pipeline (docker/linux-sbom/, docker/windows-sbom/) Run the same pipeline inside a container image Docker, PowerShell, Python
Project registration (add-project.yml, Add-Project.ps1) Validate and upsert a project's pipeline config into a consumer's repository variables GitHub Actions, Python, PowerShell
Human escalation (New-HumanEscalation.ps1, Get-HumanEscalations.ps1) Create/update structured, labeled GitHub issues for agent-unsolvable blockers PowerShell, gh CLI
Repo onboarding (Enable-RepoIssueTracking.ps1) Idempotently enable Issues + seed the escalation label on a repo PowerShell, gh CLI
Standards compliance (docs/architecture/, this wiki, standards-compliance-recheck.yml) Stamp and re-check this repo's compliance against repo-standards-review Markdown, GitHub Actions, self-hosted runner

Component View

Component Container Responsibility
build-virtualbox.ps1/.sh VM provisioning Create a VirtualBox VM from an explicit, no-default identity input set
provision-windows-guest.py VM provisioning Drive unattended Windows guest setup
vnc-bootstrap.py, vnc-console.sh VM provisioning VNC-based bootstrap/console access to a guest VM
Run-Pipeline.ps1/.sh Native SBOM pipeline Orchestrate checkout, VIPM, build, and report stages for one project
Build-Sbom.ps1 Native SBOM pipeline Dot-sourced library of SBOM-building helpers
linux_sbom_pipeline.py, windows_sbom_pipeline.ps1 Containerized SBOM pipeline In-container equivalents of the native pipeline
Add-Project.ps1 Project registration Local validation + gh workflow run add-project.yml dispatch
New-HumanEscalation.ps1 Human escalation Idempotent create/update of a structured escalation issue
Get-HumanEscalations.ps1 Human escalation Cross-repo dashboard of open escalations
Enable-RepoIssueTracking.ps1 Repo onboarding Enable Issues + seed the needs-human-decision label

Deployment View

  • Environments: GitHub-hosted ubuntu-latest runners (for registration/ dashboard/escalation logic); self-hosted runners (Windows+LabVIEW, Ubuntu+LabVIEW, and now standards-review-local) for anything needing real LabVIEW/VIPM or private-repo local credentials.
  • Nodes: VirtualBox VMs provisioned by this engine (Windows 11 + LabVIEW/ VIPM, Ubuntu 24.04 + LabVIEW/VIPM); the physical host machine running the standards-review-local self-hosted runner (same host already running the VITechnologies/SandboxSBOMReporting runner, as a separate, independently-registered runner instance).
  • Runtime dependencies: NI LabVIEW + VIPM (on provisioned VMs); Docker (for the containerized pipelines); gh CLI + GitHub Actions (throughout); PowerShell 7+ and Python 3.11+ (cross-platform script runtime).

Correspondence And Rationale

  • Requirement-to-component notes: see Requirements-Traceability-Matrix for the full REQ-### -> component linkage.
  • Decision rationale: see the ADR Index below.
  • Known tradeoffs: standards-review-local binds one specific gate (compliance re-certification) to one physical machine's private credentials and PDF corpus -- deliberately kept off the public upstream's own CI token scope (see docs/architecture/standards-compliance.md's living re-certification policy), at the cost of that check being unavailable on any fork that doesn't set up the same local runner.

ADR Index

  • ADR-0001: Adopt GitFlow for release governance (docs/architecture/adr/ADR-0001-adopt-gitflow-for-release-governance.md, in the main repo, not this wiki -- see Home for why ADRs stay there while this packet and the SRS/RTM live here).

Clone this wiki locally