Pipeline architecture

Execution pipeline

socotra.yaml  →  Parser  →  StateReader  →  DiffEngine  →  PlanEngine  →  Executor
(YAML)            (Parse)    (Scan FS)        (Detect Drift)  (Order Steps)   (Apply)

Data flows in one direction. Each runtime stage above is its own project and never reaches sideways or backwards. Around the pipeline sit three supporting components: Core (shared domain types), TemplateRegistry (template fetching and caching), and CLI (the composition root). Together that is eight components.

The eight components

• Socotra.Core — pure domain models, Result<T>, change types, plan types. Zero external dependencies.
• Socotra.Parser — deserializes YAML into a typed SocotraConfig using YamlDotNet and FluentValidation.
• Socotra.StateReader — scans the filesystem for the actual .sln, .csproj, packages, and template files.
• Socotra.DiffEngine — computes the unordered set of differences between desired and actual state.
• Socotra.PlanEngine — orders the diff into a dependency-correct execution plan using Kahn's algorithm and validates it for cycles.
• Socotra.Executor — runs the plan with progress reporting, rollback journal, and atomic file writes.
• Socotra.TemplateRegistry — fetches, caches, and applies templates from built-in, GitHub, and local sources.
• Socotra.Cli — the presentation layer and composition root, built on System.CommandLine and Spectre.Console.

The Result monad

All cross-component data flows as Result<T> — success carries a value, failure carries an error string. This keeps error handling explicit and removes hidden exceptions from the happy path. The built-in result-pattern template exposes the same idea to your generated code.