Architecture Guide

Architecture Guide

Primary purpose

This page explains how Nuplane works structurally: the control loop, the major modules, the ownership split between core and optional modules, and how repository areas map to user-facing concepts.

High-level control loop

Nuplane’s architecture centers on a deterministic control loop:

1. collect desired package state from configured sources;
2. compare desired state with the current active state;
3. resolve package versions and compute a diff;
4. apply transactional per-package changes to the deterministic store;
5. expose authoritative package and operational read surfaces;
6. emit change signals for the host to react to.

• Applicability: Core

Module map

Repository area	Product concept	Applicability	Responsibility
src/Nuplane/	Core composition and builder surface	Core	Wires the runtime story together and exposes host-facing setup entry points
src/Nuplane.Runtime/	Reconciliation engine	Core	Owns desired-vs-actual reconciliation and runtime orchestration
src/Nuplane.Store/	Deterministic package store	Core	Owns transactional storage, activation pointers, and LKG safety
src/Nuplane.NuGet/	Feed resolution and acquisition	Core	Integrates with NuGet feeds and package acquisition
src/Nuplane.Abstractions/	Shared contracts	Core	Keeps common interfaces and models lightweight
src/Nuplane.Sources.Directory/	Directory-backed desired source	Core	Adds local .nupkg directory feed behavior
src/Nuplane.Admin/ + src/Nuplane.Admin.Api/	Admin and HTTP read surfaces	Core	Exposes management and read routes for package and operational state
src/Nuplane.Loading/ + src/Nuplane.Loading.Api/	Optional runtime loading	Optional Module	Adds load-state and assembly-loading behavior when the host opts in
src/Nuplane.Loading.Hosting/	Loading module composition helpers	Optional Module	Adds module-owned builder integration for loading scenarios

Ownership boundaries

Core behavior

• Applicability: Core
• Runtime package reconciliation, deterministic storage, transactional safety, query-first state access, and observability belong to the main Nuplane product story.

Optional module behavior

• Applicability: Optional Module
• Assembly loading, load-state-specific reads, and loading-specific composition stay outside the baseline runtime story until a host explicitly installs them.

Roadmap-stage context

• Applicability: Phase-Based
• Phase 2 governance and reproducibility work, Phase 3 optional loading, and later convergence/rollout work live in the roadmap/spec system as staged context. The wiki summarizes their role but does not replace docs/roadmap.md.

Repository-to-concept mapping

Reader concept	Repository anchor
Host-neutral runtime control plane	README.md, src/Nuplane.Runtime/
Deterministic store and LKG semantics	README.md, src/Nuplane.Store/
Feed-backed desired state	README.md, src/Nuplane.NuGet/, src/Nuplane.Sources.Directory/
Query-first package and operational reads	README.md, src/Nuplane.Admin/, src/Nuplane.Admin.Api/
Optional load-state and assembly access	README.md, src/Nuplane.Loading/, src/Nuplane.Loading.Api/
Staged feature evolution	docs/roadmap.md, accepted specs under specs/

Architecture notes that matter to contributors

Query surfaces vs observer callbacks

• Applicability: Recently Changed
• The repository currently emphasizes query-first reads for authoritative state, with observers acting as supplemental invalidation or logging signals.
• That matters when you are reading sample code or adding documentation, because the product story should not drift back toward “event history as the canonical state model.”

Module-owned registration pattern

• Applicability: Recently Changed
• Optional modules now own their own registration helpers and builder integration packages.
• That keeps the core package from absorbing module-specific implementation details.

Phase 4 convergence and rollout work

• Applicability: Evolving
• The roadmap documents broader convergence and administrative patterns that are real planning surfaces, but they are not the universal baseline for every current host.

What this guide intentionally does not replace

This guide points to repository-owned sources for:

• exact admin route shape and HTTP contracts;
• full phase-history detail and acceptance matrices;
• maintainer-only operational procedures;
• low-level implementation mechanics that are better learned in code.

Related pages

• Overview
• Usage Guide
• Concepts and Glossary
• Source References

Canonical repository anchors

• README.md
• docs/roadmap.md
• src/Nuplane/
• src/Nuplane.Runtime/
• src/Nuplane.Store/
• src/Nuplane.Loading/
• src/Nuplane.Admin.Api/