# powershell/dsc architecture

> Architecture diagram of the GitHub repository powershell/dsc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/powershell/dsc
- Repository: https://github.com/powershell/dsc

## Overview

##### Project Type and Purpose
- DSCv3 is an open-source, cross-platform command-line tool for Desired State Configuration. It uses Rust and JSON schemas to declaratively author, discover, and invoke “resources” that enforce system state, without depending on PowerShell (though it can interoperate with PowerShell-based DSC resources).
- It’s structured as a Rust workspace comprising:
- A core CLI (`dsc`)
- A core library (`dsc_lib`) implementing parsing, schema validation, discovery, and configuration logic
- Multiple resource/extension crates (e.g., `registry`, `osinfo`, `runcommandonset`, `dscecho`, plus PowerShell adapters)
- A large `schemas/` directory housing JSON schema definitions for config documents, resources, and outputs
- Documentation and examples under `docs/` and `dsc/examples/`

##### High-Level Architecture Components
A. User Interface
- `dsc` CLI binary: entry point, parses command-line args, selects subcommands (config, resource, schema, completer)
B. Core Library
- `dsc_lib`:
– Parser (configuration documents, expression AST)
– Function evaluator (base64, concat, envvar, arithmetic, etc.)
– Discovery and dependency resolver (builds execution order)
– Configuration engine (invokes resources via resource_command module)
– Schema loader/validator (loads JSON schemas from `schemas/`)
C. Resource Plugins / Extensions
- Rust-based resource crates (e.g., `registry`, `osinfo`, `runcommandonset`, `brew`, `apt`, experimental, community resources)
- PowerShell adapter (invokes PS cmdlets or scripts)
- Each plugin exposes a CLI interface or JSON-over-stdout protocol and a manifest (`*.dsc.resource.json`)
D. Schemas & Metadata
- `schemas/`: JSON files defining request/response contracts for config docs, resource operations, CLI outputs
- Used by CLI and library for validation and documentation
E. Tests & Examples
- PowerShell integration tests (`dsc/tests/*.ps1`)
- Rust unit/integration tests per crate
- Example config documents under `dsc/examples/`

##### Component Interactions and Data Flow
1. User runs: `dsc <subcommand> [options]`
2. CLI (`dsc`) → Core library (`dsc_lib`): parse args, load JSON/YAML config document
3. Core library:
a. Validate document against JSON schema
b. Build resource dependency graph via discovery
c. Evaluate expressions and parameters
4. For each resource in graph:
a. Launch resource plugin process (Rust binary or PowerShell script)
b. Pass operation (Get/Set/Test) and parameters as JSON over stdin or args
c. Plugin executes idempotent logic, returns JSON status and outputs
5. Core library collects results, formats according to schema, CLI prints to console or returns exit code
6. CLI may also expose schema & help via built-in subcommands (e.g., `dsc schema config.document`)

##### Architectural Patterns & Principles
- Modular plugin architecture (Extension/Adapter pattern): new resources can be added as separate crates or scripts
- Schema-driven design: JSON Schema files act as source of truth for validation and tooling
- Layered structure: CLI layer → library layer → plugin layer
- Process isolation: each resource runs in its own process for fault isolation
- Workspaces & crates: clear separation of concerns via Rust workspace and dedicated crates

##### Checklist
- [ ] Group plugin crates under a “Resource Plugins” cluster
- [ ] Include schema repository as a shared service
- [ ] Annotate processes and interfaces (stdin/stdout, command-line args)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers
    subgraph "User Interface" 
        direction TB
        dscCLI["dsc CLI"]:::ui
    end

    subgraph "Core Library (dsc_lib)" 
        direction TB
        parser["Parser & AST"]:::core
        evaluator["Function Evaluator"]:::core
        discovery["Discovery & Dependency Resolver"]:::core
        engine["Configuration Engine"]:::core
        invocation["Resource Invocation"]:::core
        schemaLoader["Schema Loader/Validator"]:::core
    end

    subgraph "Schemas & Metadata" 
        direction TB
        schemas["JSON Schema Store"]:::artifact
    end

    subgraph "Resource Plugins" 
        direction TB
        registry["Registry Plugin"]:::plugin
        osinfo["OSInfo Plugin"]:::plugin
        runcmd["RunCommandOnSet Plugin"]:::plugin
        dscecho["Dscecho Plugin"]:::plugin
        processP["Process Plugin"]:::plugin
        reboot["RebootPending Plugin"]:::plugin
        psAdapter["PowerShell Adapter"]:::plugin
    end

    subgraph "Examples & Documentation"
        direction TB
        examples["Examples & Docs"]:::artifact
    end

    subgraph "Integration Tests"
        direction TB
        tests["PowerShell & Plugin Tests"]:::artifact
    end

    %% Connections
    dscCLI -->|"calls"| parser
    dscCLI -->|"calls"| schemaLoader
    parser -->|"AST"| evaluator
    parser -->|"uses"| schemaLoader
    evaluator -->|"evaluates"| engine
    discovery -->|"builds graph"| engine
    engine -->|"invoke resources"| invocation
    invocation -->|"starts process"| registry
    invocation -->|"starts process"| osinfo
    invocation -->|"starts process"| runcmd
    invocation -->|"starts process"| dscecho
    invocation -->|"starts process"| processP
    invocation -->|"starts process"| reboot
    invocation -->|"starts process"| psAdapter
    schemas -->|"read schemas"| schemaLoader
    engine -->|"results"| dscCLI
    examples --> dscCLI
    tests --> schemaLoader

    %% Click Events
    click dscCLI "https://github.com/powershell/dsc/blob/main/dsc/src/main.rs"
    click parser "https://github.com/powershell/dsc/blob/main/dsc_lib/src/parser/mod.rs"
    click evaluator "https://github.com/powershell/dsc/blob/main/dsc_lib/src/functions/mod.rs"
    click discovery "https://github.com/powershell/dsc/blob/main/dsc_lib/src/discovery/mod.rs"
    click engine "https://github.com/powershell/dsc/blob/main/dsc_lib/src/configure/mod.rs"
    click invocation "https://github.com/powershell/dsc/blob/main/dsc_lib/src/dscresources/resource_manifest.rs"
    click schemaLoader "https://github.com/powershell/dsc/blob/main/dsc_lib/src/schemas/mod.rs"
    click schemas "https://github.com/powershell/dsc/tree/main/schemas/"
    click registry "https://github.com/powershell/dsc/blob/main/registry/src/main.rs"
    click osinfo "https://github.com/powershell/dsc/blob/main/osinfo/src/main.rs"
    click runcmd "https://github.com/powershell/dsc/blob/main/runcommandonset/src/main.rs"
    click dscecho "https://github.com/powershell/dsc/blob/main/dscecho/src/main.rs"
    click processP "https://github.com/powershell/dsc/blob/main/process/src/main.rs"
    click reboot "https://github.com/powershell/dsc/blob/main/reboot_pending/reboot_pending.resource.ps1"
    click psAdapter "https://github.com/powershell/dsc/blob/main/powershell-adapter/psDscAdapter/psDscAdapter.psm1"
    click examples "https://github.com/powershell/dsc/tree/main/dsc/examples/"
    click tests "https://github.com/powershell/dsc/tree/main/dsc/tests/"

    %% Styles
    classDef ui fill:#cfe2f3,stroke:#344e6e,color:#0b2344;
    classDef core fill:#d9ead3,stroke:#3c763d,color:#1d4f1f;
    classDef plugin fill:#ffe599,stroke:#7f6000,color:#503800;
    classDef artifact fill:#f2f2f2,stroke:#666666,color:#333333;
```
