powershell-module-architect

PowerShell Module Architect

Purpose

Provides PowerShell module design and architecture expertise specializing in creating structured, reusable, and maintainable PowerShell modules. Focuses on module architecture, function design, cross-version compatibility, and profile optimization for enterprise PowerShell environments.

When to Use

• Transforming scattered scripts into structured, reusable modules
• Designing module architecture with public/private function separation
• Creating cross-version compatible modules (PowerShell 5.1 & 7+)
• Optimizing PowerShell profiles for faster load times
• Building advanced functions with proper parameter validation

Quick Start

Invoke this skill when:

• Transforming scattered scripts into structured, reusable modules
• Designing module architecture with public/private function separation
• Creating cross-version compatible modules (PowerShell 5.1 & 7+)
• Optimizing PowerShell profiles for faster load times
• Building advanced functions with proper parameter validation

Do NOT invoke when:

• Simple one-off scripts that won't be reused (use powershell-5.1-expert or powershell-7-expert)
• Already have well-structured modules needing functionality additions (use relevant domain skill)
• UI development (use powershell-ui-architect instead)
• Security hardening (use powershell-security-hardening instead)

Decision Framework

When to Create a Module

Scenario	Recommendation
3+ related functions	Create module
Cross-team sharing needed	Create module + manifest
Single-use automation	Keep as script
Complex parameter sets	Advanced function in module
Version compatibility needed	Module with compatibility layer

Module Structure Decision

Script Organization Need
│
├─ Few related functions (3-10)?
│  └─ Single .psm1 with inline functions
│
├─ Many functions (10+)?
│  └─ Dot-source pattern (Public/Private folders)
│
├─ Publishing to gallery?
│  └─ Full manifest + tests + docs
│
└─ Team collaboration?
   └─ Git repo + CI/CD + Pester tests

Core Workflow: Transform Scripts into Module

Use case: Refactor 10-50 scattered .ps1 scripts into organized module

Step 1: Analysis

# Inventory existing scripts
$scripts = Get-ChildItem -Path ./scripts -Filter *.ps1 -Recurse

# Analyze function signatures
foreach ($script in $scripts) {
    $content = Get-Content $script.FullName -Raw
    $functions = [regex]::Matches($content, 'function\s+(\S+)')
    
    Write-Host "$($script.Name): $($functions.Count) functions"
}

# Expected output:
# AD-UserManagement.ps1: 12 functions
# AD-GroupManagement.ps1: 8 functions
# Common-Helpers.ps1: 15 functions (candidates for Private/)

Step 2: Design Module Structure

# Create module skeleton
$moduleName = "Organization.ActiveDirectory"
$modulePath = "./modules/$moduleName"

New-Item -Path "$modulePath/Public" -ItemType Directory -Force
New-Item -Path "$modulePath/Private" -ItemType Directory -Force
New-Item -Path "$modulePath/Tests" -ItemType Directory -Force
New-Item -Path "$modulePath/$moduleName.psm1" -ItemType File -Force
New-Item -Path "$modulePath/$moduleName.psd1" -ItemType File -Force

Step 3: Categorize Functions

Public functions (exported to users):
  ├─ Get-OrgADUser
  ├─ New-OrgADUser
  ├─ Set-OrgADUser
  ├─ Remove-OrgADUser
  └─ ... (user-facing functions)

Private functions (internal helpers):
  ├─ _ValidateDomainConnection
  ├─ _BuildDistinguishedName
  ├─ _ConvertToCanonicalName
  └─ ... (utility functions)

Step 4: Implement Module File

# Organization.ActiveDirectory.psm1

# Dot-source Private functions first
$Private = @(Get-ChildItem -Path $PSScriptRoot\Private\*.ps1 -ErrorAction SilentlyContinue)
foreach ($import in $Private) {
    try {
        . $import.FullName
    } catch {
        Write-Error "Failed to import private function $($import.FullName): $_"
    }
}

# Dot-source Public functions
$Public = @(Get-ChildItem -Path $PSScriptRoot\Public\*.ps1 -ErrorAction SilentlyContinue)
foreach ($import in $Public) {
    try {
        . $import.FullName
    } catch {
        Write-Error "Failed to import public function $($import.FullName): $_"
    }
}

# Export Public functions explicitly
Export-ModuleMember -Function $Public.BaseName

Step 5: Create Module Manifest

# Generate manifest
$manifestParams = @{
    Path              = "$modulePath/$moduleName.psd1"
    RootModule        = "$moduleName.psm1"
    ModuleVersion     = '1.0.0'
    Author            = 'IT Team'
    CompanyName       = 'Organization'
    Description       = 'Active Directory management functions'
    PowerShellVersion = '5.1'  # Minimum version
    FunctionsToExport = @(
        'Get-OrgADUser',
        'New-OrgADUser',
        'Set-OrgADUser',
        'Remove-OrgADUser'
    )
    VariablesToExport = @()
    AliasesToExport   = @()
}
New-ModuleManifest @manifestParams

Step 6: Add Pester Tests

# Tests/Module.Tests.ps1
BeforeAll {
    Import-Module "$PSScriptRoot/../Organization.ActiveDirectory.psd1" -Force
}

Describe "Organization.ActiveDirectory Module" {
    It "Exports expected functions" {
        $commands = Get-Command -Module Organization.ActiveDirectory
        $commands.Count | Should -BeGreaterThan 0
    }
    
    It "Has valid module manifest" {
        $manifest = Test-ModuleManifest -Path "$PSScriptRoot/../Organization.ActiveDirectory.psd1"
        $manifest.Version | Should -Be '1.0.0'
    }
}

Describe "Get-OrgADUser" {
    It "Accepts Identity parameter" {
        { Get-OrgADUser -Identity "testuser" -WhatIf } | Should -Not -Throw
    }
}

Quick Reference: Advanced Function Template

function Get-OrgUser {
    <#
    .SYNOPSIS
        Retrieves Active Directory user by name.
    
    .DESCRIPTION
        Queries Active Directory for user object and returns detailed properties.
    
    .PARAMETER Name
        The username or SamAccountName to search for.
    
    .EXAMPLE
        Get-OrgUser -Name "jdoe"
        
        Returns all properties for user jdoe.
    
    .EXAMPLE
        "jdoe", "asmith" | Get-OrgUser
        
        Retrieves multiple users via pipeline.
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory, ValueFromPipeline)]
        [ValidateNotNullOrEmpty()]
        [string]$Name
    )
    
    process {
        Get-ADUser -Identity $Name -Properties *
    }
}

Integration Patterns

powershell-5.1-expert

• Handoff: Module architecture designed → 5.1 expert implements Windows-specific functions
• Collaboration: Module structure decisions considering 5.1 compatibility

powershell-7-expert

• Handoff: Module structure defined → 7 expert adds modern syntax optimizations
• Collaboration: Dual-mode functions using version detection

windows-infra-admin

• Handoff: Module architecture → Windows admin implements domain-specific logic
• Shared responsibility: Active Directory, GPO, DNS module functions

azure-infra-engineer

• Handoff: Module patterns → Azure engineer builds cloud automation modules
• Integration: Cross-cloud modules combining on-prem & Azure

Red Flags - When to Escalate

Observation	Action
100+ functions in single module	Consider splitting into sub-modules
Complex cross-version issues	Consult powershell-5.1 and 7 experts
Performance <1s profile load	Apply lazy loading patterns
Security-sensitive operations	Involve powershell-security-hardening

Additional Resources

• Detailed Technical Reference: See REFERENCE.md

  • Profile optimization workflow
  • Module manifest template
  • Dynamic parameters pattern

• Code Examples & Patterns: See EXAMPLES.md

  • Anti-patterns (monolithic files, missing help)
  • Cross-version compatibility patterns
  • Advanced parameter validation