Repository navigation
Architecture Packet
sergio velderrain edited this page Nov 6, 2026
·
24 revisions
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.
- 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.
| 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) |
- 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 | 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 | 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 |
- Environments: GitHub-hosted
ubuntu-latestrunners (for registration/ dashboard/escalation logic); self-hosted runners (Windows+LabVIEW, Ubuntu+LabVIEW, and nowstandards-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-localself-hosted runner (same host already running theVITechnologies/SandboxSBOMReportingrunner, as a separate, independently-registered runner instance). - Runtime dependencies: NI LabVIEW + VIPM (on provisioned VMs); Docker (for
the containerized pipelines);
ghCLI + GitHub Actions (throughout); PowerShell 7+ and Python 3.11+ (cross-platform script runtime).
- Requirement-to-component notes: see
Requirements-Traceability-Matrix for the full
REQ-### -> componentlinkage. - Decision rationale: see the ADR Index below.
- Known tradeoffs:
standards-review-localbinds 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 (seedocs/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-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).