windows-iac-vm-tooling/docs/01-overview/architecture.md

🏗️ Architecture Overview

System Components

This project implements a complete automated build, package, and test pipeline for Windows applications. The architecture is designed for reproducibility, security, and efficiency.

Core Components

Component	Technology	Purpose	Location
Image Builder	Packer	Create golden Windows templates	packer/windows.pkr.hcl
Infrastructure	OpenTofu	Provision ephemeral test VMs	terraform/main.tf
Automation	Ansible	Verify installations	ansible/pipeline.yml
CI/CD	Forgejo Actions	Orchestrate pipeline	.forgejo/workflows/release.yml

---

Architecture Diagram

flowchart TB
    subgraph Development["Developer Workflow"]
        Code[Write Code] --> Commit[Git Commit] --> Push[Git Push]
    end
    
    subgraph Pipeline["Forgejo Pipeline"]
        Push --> |Trigger| Build["Build & Sign"]
        Build --> Provision["Provision VM"]
        Provision --> Verify["Verify"]
        Verify --> Artifacts["Artifacts"]
    end
    
    subgraph Build["Build Stage"]
        direction LR
        Compile[Cross-Compile<br/>MinGW] --> Package[Package<br/>NSIS] --> Sign[Code Sign<br/>osslsigncode]
    end
    
    subgraph Infrastructure["Proxmox Infrastructure"]
        Template[Windows Template<br/>Packer Built] --> Clone[Clone VM<br/>OpenTofu] --> TestVM[Test VM<br/>Ansible]
    end
    
    Build --> Template
    Provision --> Clone
    Verify --> TestVM
    
    style Development fill:#e3f2fd
    style Pipeline fill:#f3e5f5
    style Build fill:#e8f5e9
    style Infrastructure fill:#fff8e1

---

Data Flow

sequenceDiagram
    participant Dev as Developer
    participant Forgejo as Forgejo CI/CD
    participant Proxmox as Proxmox Host
    participant VM as Windows VM
    participant Artifact as Artifacts
    
    Dev->>Forgejo: Push code changes
    Forgejo->>Forgejo: Cross-compile (MinGW)
    Forgejo->>Forgejo: Package (NSIS)
    Forgejo->>Forgejo: Sign binary (osslsigncode)
    
    Forgejo->>Proxmox: Provision VM (OpenTofu)
    Proxmox->>VM: Clone from template
    VM->>VM: Boot Windows
    
    Forgejo->>VM: Deploy signed installer
    Forgejo->>VM: Run Ansible playbook
    VM->>Forgejo: Test results
    
    alt Test Passed
        Forgejo->>Artifact: Publish installer
    else Test Failed
        Forgejo->>Dev: Notify failure
    end
    
    Proxmox->>Proxmox: Destroy VM (cleanup)

---

Design Decisions

Why This Architecture?

Decision	Alternative	Rationale
Packer + ISO	PXE Boot	Self-contained, reproducible, no TFTP/DHCP infrastructure needed
Cross-compile on Linux	Native Windows build	Faster builds, simpler tooling, consistent environment
Code signing on Linux	Windows HSM	Native osslsigncode, easier certificate management
Ephemeral VMs	Persistent test VMs	Fresh environment each run, no drift, automatic cleanup
OpenTofu	Terraform/OpenTF	Open-source fork, community support, no license concerns

Component Responsibilities

Phase	Responsibility	Tool
1. Build	Create reproducible Windows template	Packer
2. Provision	Deploy ephemeral test environment	OpenTofu
3. Compile	Build Windows binaries from Linux	MinGW
4. Package	Create installer executable	NSIS
5. Sign	Authenticode signing with timestamp	osslsigncode
6. Verify	Smoke test on live Windows	Ansible

---

Technology Stack

graph LR
    subgraph CI["CI/CD Layer"]
        Forgejo["Forgejo Actions"]
        ArchLinux["Arch Linux Container"]
    end
    
    subgraph Build["Build Layer"]
        MinGW["MinGW GCC"]
        NSIS["NSIS"]
        Sign["osslsigncode"]
    end
    
    subgraph Infra["Infrastructure Layer"]
        OpenTofu["OpenTofu"]
        Packer["Packer"]
        Proxmox["Proxmox VE"]
    end
    
    subgraph Test["Testing Layer"]
        Ansible["Ansible"]
        WinVM["Windows VM"]
    end
    
    CI --> Build
    CI --> Infra
    Infra --> Test
    Build --> Test
    
    style CI fill:#e1f5fe
    style Build fill:#e8f5e9
    style Infra fill:#fff3e0
    style Test fill:#fce4ec

Layer	Technologies
CI/CD	Forgejo Actions, Arch Linux container
Build Tools	MinGW GCC, NSIS, osslsigncode
Infrastructure	Packer, OpenTofu, Proxmox VE
Testing	Ansible, Windows 11 LTSC

---

Environment Details

Proxmox Host Configuration

Setting	Value
Host	la-vmh-07
API Endpoint	https://proxmox-host:8006/
Storage	local-lvm (templates), local (ISOs)
Network	vmbr0

Windows Configuration

Setting	Value
Edition	Windows 11 Enterprise LTSC 2024
Administrator	Built-in Administrator account
WinRM	Enabled via ConfigureRemotingForAnsible.ps1
Firewall	Private profile disabled

---

File Manifest

graph TD
    subgraph Source["Source Files"]
        Src["src/main.c"]
        NSIS["installer.nsi"]
    end
    
    subgraph Config["Configuration"]
        Packer["packer/windows.pkr.hcl"]
        Answer["packer/Autounattend.xml"]
        Terraform["terraform/main.tf"]
        Ansible["ansible/pipeline.yml"]
        Workflow[".forgejo/workflows/release.yml"]
    end
    
    subgraph Docs["Documentation"]
        Readme["README.md"]
        Index["docs/index.md"]
        Arch["docs/01-overview/architecture.md"]
    end
    
    Src --> Packer
    Src --> Workflow
    NSIS --> Workflow
    Packer --> Terraform
    Terraform --> Ansible
    Ansible --> Workflow
    Readme --> Index
    Index --> Arch
    
    style Source fill:#e3f2fd
    style Config fill:#e8f5e9
    style Docs fill:#fff3e0

---

Next Steps

Goal	Next Document
Set up prerequisites	ISO Requirements
Build template	Packer Configuration
Configure secrets	Secret Management
Run pipeline	Forgejo Workflows

---

← Documentation Index | → ISO Requirements | ← README