Architecture

How Socotra works

A unidirectional pipeline of small, single-responsibility .NET projects.

Overview

Socotra is a collection of independent .NET projects composed into a single CLI. Each project has one job and depends only on projects "to its left" in the pipeline. Data flows through the Result<T> monad — success or explicit error.

Pipeline diagram

Each box is an independent .NET project. Result<T> flows unidirectionally left → right.

Stage responsibilities

Stage	Input	Output	Responsibility
Parser	socotra.yaml	Typed model	Deserialize YAML, surface schema errors
StateReader	Filesystem	Actual-state model	Scan .sln, .csproj, packages, template files
DiffEngine	Desired + Actual	Unordered change set	Compute drift; classify add/modify/destroy
PlanEngine	Change set	Ordered plan	Topological sort; assign risk levels
Executor	Plan	Result	Run dotnet commands; atomic writes; rollback on failure

Template subsystem

The template subsystem (Socotra.TemplateRegistry) is a parallel pipeline used by ApplyTemplate steps:

TemplateSourceParser → TemplateResolver → TemplateFetcherDispatcher
        → BuiltIn / GitHub / LocalPath Fetcher
        → LocalRegistryStore
        → NamespaceDetector
        → TemplateApplier
        → NormalizedFileWriter (atomic .tmp write + guard header)

Principles

Single responsibility per project — no "manager" or "service" grab-bags.
No circular dependencies — stages strictly depend left-to-right.
Explicit errors via Result<T>; exceptions don't cross boundaries.
Atomic writes via .tmp intermediate files.
Pure plan — no I/O during plan computation beyond reading state.

Schema 1.1 · CLI 1.0

PreviousCI/CD integration