# shine0078/home-lab architecture

> Architecture diagram of the GitHub repository shine0078/home-lab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shine0078/home-lab
- Repository: https://github.com/shine0078/home-lab

## Overview

1. This repository is an end-to-end, scripted Active Directory home lab. The core system is a Hyper-V host running one Windows Server 2022 domain controller (`DC01`) and two Windows 11 client VMs, all tied together on an internal virtual switch.

2. The architecture is split into setup layers:
   - `hyperv/` provisions the virtual machines and network.
   - `scripts/` configures the Windows/AD services after the OS is installed.
   - `dsc/` provides a declarative alternative using Desired State Configuration.
   - `modules/ADHomeLab` holds reusable PowerShell functions shared by the operational scripts.

3. The infrastructure boundary starts on the Hyper-V host. `Provision-All.ps1` creates the lab VMs and internal switch, then unattend XML files automate the initial OS install for Server 2022 and Windows 11. This is the bootstrap layer before any AD-specific configuration happens.

4. `DC01` is the control plane for the lab. It hosts Active Directory Domain Services, DNS, DHCP, Group Policy, and Windows Event Forwarding collection. Most other automation ultimately targets this machine because it owns identity, policy, and central logging.

5. The client boundary is the two Windows 11 machines. They are domain-joined endpoints used to validate policy, security controls, and operational scenarios. Their main data flow is outbound telemetry and event forwarding back to `DC01`.

6. The configuration workflow is intentionally staged:
   - `01-Setup-DC.ps1` establishes the domain controller.
   - `02-Join-Domain.ps1` joins clients to the domain.
   - `03-Configure-GPOs.ps1` applies baseline and advanced Group Policy.
   - `04-Create-Users.ps1` loads users from `data/users.csv`.
   - `05-Validate-Lab.ps1` checks the environment.
   - Additional scripts handle hardening, monitoring, backup, restore, and RBAC.

7. Policy and identity data are mostly file-driven. `data/users.csv` feeds bulk user creation, `data/monitored-events.csv` defines monitored security/event patterns, and `config/gpo-exports/` is reserved for exported GPO artifacts. This makes the lab reproducible and keeps configuration outside the scripts themselves.

8. Security and governance are a major subsystem rather than an add-on. The scripts and docs implement STIG/CIS-inspired hardening, password and firewall policy, ASR rules, audit settings, NTLM/SMB protections, and RBAC delegation. The `docs/security-baseline.md` and `docs/rbac-matrix.md` files describe these controls at a design level.

9. Monitoring and operations center on Windows Event Forwarding plus scheduled-task-based alerting. `scripts/07-Setup-Monitoring.ps1` configures collection/forwarding, while the `docs/security-dashboard.md` and the runbooks document how alerts are interpreted and responded to. This creates a clear flow from clients to the domain controller’s logging/monitoring role.

10. Backup and recovery are separate operational paths. `scripts/08-Backup-Lab.ps1` and `scripts/09-Restore-Lab.ps1` support disaster recovery, with `docs/backup-strategy.md` defining the intended RPO/RTO and recovery process. The runbooks tie specific failure modes to restore actions.

11. The repository also includes a test and CI boundary. `tests/` contains Pester-based validation and syntax checks, while `.github/workflows/lint.yml` runs PowerShell linting and tests in GitHub Actions. This enforces script quality without changing the lab topology itself.

12. `vagrant/` is an alternate provisioning path, but it still targets the same underlying lab model: a domain controller plus clients on Hyper-V. In diagram terms, it is an optional entry point to the same environment rather than a separate runtime system.

Main entry points: [`scripts/06-Harden-Baseline.ps1`](https://github.com/shine0078/home-lab/blob/master/scripts/06-Harden-Baseline.ps1) (Ops security), [`hyperv/Provision-All.ps1`](https://github.com/shine0078/home-lab/blob/master/hyperv/Provision-All.ps1) (Provision All), [`modules/ADHomeLab/ADHomeLab.psm1`](https://github.com/shine0078/home-lab/blob/master/modules/ADHomeLab/ADHomeLab.psm1) (ADHomeLab module), [`scripts/04-Create-Users.ps1`](https://github.com/shine0078/home-lab/blob/master/scripts/04-Create-Users.ps1) (Create users)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Bootstrap"]
  node_hyperv_host["Hyper-V host"]
  node_internal_switch{{"Internal switch<br/>network"}}
  node_provision_all["Provision All<br/>provision script<br/>[Provision-All.ps1]"]
  node_unattend_images["Unattend images<br/>install automation"]
  node_vagrant_entry["Vagrant entry<br/>alternate bootstrap<br/>[bootstrap-dc.ps1]"]
end

subgraph group_lab["Lab runtime"]
  node_dc01[("DC01<br/>domain controller")]
  node_clients["Win11 clients<br/>endpoints"]
end

subgraph group_ops["Operations"]
  node_adhomelab_module["ADHomeLab module<br/>shared module<br/>[ADHomeLab.psm1]"]
  node_setup_dc["Setup DC<br/>domain bootstrap<br/>[01-Setup-DC.ps1]"]
  node_join_domain["Join domain<br/>endpoint onboarding<br/>[02-Join-Domain.ps1]"]
  node_configure_gpos["Configure GPOs<br/>policy baseline"]
  node_user_provision["Create users<br/>identity seeding"]
  node_ops_security["Ops security<br/>hardening and recovery"]
  node_validate_lab["Validate lab<br/>verification"]
end

subgraph group_data["Data and docs"]
  node_users_csv["Users CSV<br/>identity data<br/>[users.csv]"]
  node_events_csv["Events CSV<br/>telemetry data"]
  node_security_docs["Security docs<br/>governance docs"]
  node_backup_docs["Backup docs<br/>recovery docs<br/>[backup-strategy.md]"]
  node_dashboard_docs["Dashboard docs<br/>monitoring docs"]
end

subgraph group_quality["Quality and alternate paths"]
  node_dsc_config["DSC config<br/>declarative alternative"]
  node_tests["Tests<br/>Pester suite<br/>[Project.Tests.ps1]"]
  node_ci_workflow["CI workflow<br/>github actions<br/>[lint.yml]"]
end

node_hyperv_host -->|"runs"| node_provision_all
node_provision_all -->|"creates"| node_internal_switch
node_provision_all -->|"uses"| node_unattend_images
node_provision_all -->|"creates"| node_dc01
node_provision_all -->|"creates"| node_clients
node_vagrant_entry -.->|"same model"| node_provision_all
node_dc01 -->|"serves"| node_clients
node_setup_dc -->|"configures"| node_dc01
node_join_domain -->|"joins"| node_clients
node_configure_gpos -->|"applies"| node_dc01
node_user_provision -->|"reads"| node_users_csv
node_user_provision -->|"writes"| node_dc01
node_ops_security -->|"hardens"| node_dc01
node_ops_security -->|"hardens"| node_clients
node_ops_security -->|"uses"| node_events_csv
node_validate_lab -->|"checks"| node_dc01
node_validate_lab -->|"checks"| node_clients
node_adhomelab_module -->|"supports"| node_setup_dc
node_adhomelab_module -->|"supports"| node_configure_gpos
node_adhomelab_module -->|"supports"| node_ops_security
node_security_docs -->|"describes"| node_ops_security
node_backup_docs -->|"describes"| node_ops_security
node_dashboard_docs -->|"guides"| node_ops_security
node_dsc_config -.->|"configures"| node_dc01
node_tests -->|"covers"| node_configure_gpos
node_tests -->|"covers"| node_user_provision
node_ci_workflow -->|"runs"| node_tests

click node_internal_switch "https://github.com/shine0078/home-lab/blob/master/hyperv/01-Create-Switch.ps1"
click node_provision_all "https://github.com/shine0078/home-lab/blob/master/hyperv/Provision-All.ps1"
click node_unattend_images "https://github.com/shine0078/home-lab/blob/master/hyperv/unattend/unattend_Server2022.xml"
click node_vagrant_entry "https://github.com/shine0078/home-lab/blob/master/vagrant/bootstrap-dc.ps1"
click node_adhomelab_module "https://github.com/shine0078/home-lab/blob/master/modules/ADHomeLab/ADHomeLab.psm1"
click node_setup_dc "https://github.com/shine0078/home-lab/blob/master/scripts/01-Setup-DC.ps1"
click node_join_domain "https://github.com/shine0078/home-lab/blob/master/scripts/02-Join-Domain.ps1"
click node_configure_gpos "https://github.com/shine0078/home-lab/blob/master/scripts/03-Configure-GPOs.ps1"
click node_user_provision "https://github.com/shine0078/home-lab/blob/master/scripts/04-Create-Users.ps1"
click node_ops_security "https://github.com/shine0078/home-lab/blob/master/scripts/06-Harden-Baseline.ps1"
click node_validate_lab "https://github.com/shine0078/home-lab/blob/master/scripts/05-Validate-Lab.ps1"
click node_users_csv "https://github.com/shine0078/home-lab/blob/master/data/users.csv"
click node_events_csv "https://github.com/shine0078/home-lab/blob/master/data/monitored-events.csv"
click node_security_docs "https://github.com/shine0078/home-lab/blob/master/docs/security-baseline.md"
click node_backup_docs "https://github.com/shine0078/home-lab/blob/master/docs/backup-strategy.md"
click node_dashboard_docs "https://github.com/shine0078/home-lab/blob/master/docs/security-dashboard.md"
click node_dsc_config "https://github.com/shine0078/home-lab/blob/master/dsc/LabDscConfiguration.ps1"
click node_tests "https://github.com/shine0078/home-lab/blob/master/tests/Project.Tests.ps1"
click node_ci_workflow "https://github.com/shine0078/home-lab/blob/master/.github/workflows/lint.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hyperv_host,node_internal_switch,node_provision_all,node_unattend_images,node_vagrant_entry toneBlue
class node_dc01,node_clients toneAmber
class node_adhomelab_module,node_setup_dc,node_join_domain,node_configure_gpos,node_user_provision,node_ops_security,node_validate_lab toneMint
class node_users_csv,node_events_csv,node_security_docs,node_backup_docs,node_dashboard_docs toneRose
class node_dsc_config,node_tests,node_ci_workflow toneIndigo
```

## Components

### Bootstrap

Hyper-V provisioning and first-boot installation layer

- **Hyper-V host**: host · Physical or local host that creates and runs the lab
- [Internal switch](https://github.com/shine0078/home-lab/blob/master/hyperv/01-Create-Switch.ps1): network · Isolated virtual network for the lab · `hyperv/01-Create-Switch.ps1`
- [Provision All](https://github.com/shine0078/home-lab/blob/master/hyperv/Provision-All.ps1): provision script · Creates the lab VMs and wires up the virtual network · `hyperv/Provision-All.ps1`
- [Unattend images](https://github.com/shine0078/home-lab/blob/master/hyperv/unattend/unattend_Server2022.xml): install automation · Answer files that automate first boot for Server 2022 and Windows 11 · `hyperv/unattend/unattend_Server2022.xml`
- [Vagrant entry](https://github.com/shine0078/home-lab/blob/master/vagrant/bootstrap-dc.ps1): alternate bootstrap · Optional provisioning path that targets the same lab model · `vagrant/bootstrap-dc.ps1`

### Lab runtime

The Active Directory domain controller and client VMs

- **DC01**: domain controller · Windows Server 2022 domain controller and lab control plane
- **Win11 clients**: endpoints · Two domain-joined Windows 11 client VMs

### Operations

Staged PowerShell automation and shared module

- [ADHomeLab module](https://github.com/shine0078/home-lab/blob/master/modules/ADHomeLab/ADHomeLab.psm1): shared module · Reusable PowerShell functions used by operational scripts · `modules/ADHomeLab/ADHomeLab.psm1`
- [Setup DC](https://github.com/shine0078/home-lab/blob/master/scripts/01-Setup-DC.ps1): domain bootstrap · Creates and configures the Active Directory foundation · `scripts/01-Setup-DC.ps1`
- [Join domain](https://github.com/shine0078/home-lab/blob/master/scripts/02-Join-Domain.ps1): endpoint onboarding · Joins client VMs to the domain · `scripts/02-Join-Domain.ps1`
- [Configure GPOs](https://github.com/shine0078/home-lab/blob/master/scripts/03-Configure-GPOs.ps1): policy baseline · Applies baseline Group Policy and security settings · `scripts/03-Configure-GPOs.ps1`
- [Create users](https://github.com/shine0078/home-lab/blob/master/scripts/04-Create-Users.ps1): identity seeding · Bulk user creation from CSV data · `scripts/04-Create-Users.ps1`
- [Ops security](https://github.com/shine0078/home-lab/blob/master/scripts/06-Harden-Baseline.ps1): hardening and recovery · Hardening, monitoring, backup, restore, and RBAC automation · `scripts/06-Harden-Baseline.ps1`
- [Validate lab](https://github.com/shine0078/home-lab/blob/master/scripts/05-Validate-Lab.ps1): verification · Checks the environment after provisioning and configuration · `scripts/05-Validate-Lab.ps1`

### Data and docs

File-driven inputs and design/runbook references

- [Users CSV](https://github.com/shine0078/home-lab/blob/master/data/users.csv): identity data · Source data for bulk account creation · `data/users.csv`
- [Events CSV](https://github.com/shine0078/home-lab/blob/master/data/monitored-events.csv): telemetry data · Monitored event patterns used by monitoring automation · `data/monitored-events.csv`
- [Security docs](https://github.com/shine0078/home-lab/blob/master/docs/security-baseline.md): governance docs · Baseline hardening and RBAC design references · `docs/security-baseline.md`
- [Backup docs](https://github.com/shine0078/home-lab/blob/master/docs/backup-strategy.md): recovery docs · Backup and restore strategy plus failure runbooks · `docs/backup-strategy.md`
- [Dashboard docs](https://github.com/shine0078/home-lab/blob/master/docs/security-dashboard.md): monitoring docs · Security dashboard and operational interpretation guidance · `docs/security-dashboard.md`

### Quality and alternate paths

Validation, CI, DSC, and Vagrant entry points

- [DSC config](https://github.com/shine0078/home-lab/blob/master/dsc/LabDscConfiguration.ps1): declarative alternative · Desired State Configuration path for the same lab outcome · `dsc/LabDscConfiguration.ps1`
- [Tests](https://github.com/shine0078/home-lab/blob/master/tests/Project.Tests.ps1): Pester suite · Syntax and behavioral checks for key scripts · `tests/Project.Tests.ps1`
- [CI workflow](https://github.com/shine0078/home-lab/blob/master/.github/workflows/lint.yml): github actions · Runs linting and tests in GitHub Actions · `.github/workflows/lint.yml`

## Connections

- Hyper-V host → Provision All: runs · Host executes the bootstrap script
- Provision All → Internal switch: creates · Bootstrap provisions the isolated network
- Provision All → Unattend images: uses · First boot is automated by answer files
- Provision All → DC01: creates · Defines the domain controller VM
- Provision All → Win11 clients: creates · Defines the client VMs
- Vagrant entry → Provision All: same model · Alternative entry point to the same lab topology
- DC01 → Win11 clients: serves · Domain, DNS, DHCP, GPO, and forwarding services support endpoints
- Setup DC → DC01: configures · Initializes the domain controller
- Join domain → Win11 clients: joins · Enrolls the clients into the domain
- Configure GPOs → DC01: applies · Stores and applies Group Policy on the controller
- Create users → Users CSV: reads · Identity data drives account creation
- Create users → DC01: writes · Creates directory objects on the domain controller
- Ops security → DC01: hardens · Security, monitoring, backup, restore, and RBAC target the controller
- Ops security → Win11 clients: hardens · Endpoint policy and control-plane settings affect clients too
- Ops security → Events CSV: uses · Monitoring definitions are file-driven
- Validate lab → DC01: checks · Validates core domain services and configuration
- Validate lab → Win11 clients: checks · Confirms endpoint state and domain join health
- ADHomeLab module → Setup DC: supports · Shared helper functions reduce duplication
- ADHomeLab module → Configure GPOs: supports · Reusable helpers back policy automation
- ADHomeLab module → Ops security: supports · Shared PowerShell logic also powers ops workflows
- Security docs → Ops security: describes · Baseline hardening and RBAC design are documented here
- Backup docs → Ops security: describes · Recovery strategy and runbooks guide restore actions
- Dashboard docs → Ops security: guides · Monitoring interpretation and alerting workflow
- DSC config → DC01: configures · Declarative alternative for the same lab environment
- Tests → Configure GPOs: covers · Pester validates policy script behavior
- Tests → Create users: covers · Tests cover user creation and parsing paths
- CI workflow → Tests: runs · GitHub Actions executes validation and linting
