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

# 🏗️ Architecture Overview

[![Architecture](https://img.shields.io/badge/Architecture-Packer%20→%20OpenTofu%20→%20Ansible-blue)](../../.forgejo/workflows/release.yml)
[![Windows](https://img.shields.io/badge/Windows-11%20LTSC-0078D6?style=flat&logo=windows)](https://www.microsoft.com/en-us/windows/windows-11-enterprise)

## 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`](../../packer/windows.pkr.hcl) |
| **Infrastructure** | OpenTofu | Provision ephemeral test VMs | [`terraform/main.tf`](../../terraform/main.tf) |
| **Automation** | Ansible | Verify installations | [`ansible/pipeline.yml`](../../ansible/pipeline.yml) |
| **CI/CD** | Forgejo Actions | Orchestrate pipeline | [`.forgejo/workflows/release.yml`](../../.forgejo/workflows/release.yml) |

---

## Architecture Diagram

```mermaid
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

```mermaid
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

```mermaid
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

```mermaid
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](../02-prerequisites/isos.md) |
| Build template | [Packer Configuration](../03-packer/configuration.md) |
| Configure secrets | [Secret Management](../02-prerequisites/secrets.md) |
| Run pipeline | [Forgejo Workflows](../06-ci-cd/forgejo-workflows.md) |

---

[← Documentation Index](../index.md) | [→ ISO Requirements](../02-prerequisites/isos.md) | [← README](../../README.md)