Architecture

A map of the solution. Each entry links to deeper documentation where it exists; where it does not yet, the path is the place to look.

Solution layout

Everything lives under src/, and src/NRI.sln is the solution Rider and dotnet load.

Project	Role
NRI.CMS	The Umbraco 17 application. Serves the public website directly.
NRI.CMS.Common	Shared types and helpers with no Umbraco dependency.
NRI.CMS.Extensions	Umbraco extensions — property editors, notification handlers, back-office additions.
NRI.CMS.E2ETests	End-to-end test suite.
UmbracoProject	Supporting Umbraco project.
docs.nri-inc.org	This site.

Front end

Umbraco renders Razor views. Interactive pieces are Svelte islands, either statically rendered or hydrated on the client, built with Vite. In development, server-side rendering runs through Vite’s module runner; in production it is a pre-built module tree invoked from .NET.

The details — the block-port pattern, when an island should be static versus hydrated, the content-expansion-depth gotcha, and the dev SSR architecture — are documented in src/NRI.CMS/Client/README.md. Read that before touching front-end or block code.

Design system

Design tokens live in src/NRI.CMS/Client/src/design-system/tokens/. colors.nri.css is the brand palette and is the source this documentation site borrows its accent colors from.

Component specifications are living HTML documents under docs/design/ in the repository root. They are the specification, not a description of one — when a component changes, the spec changes in the same commit.

Deployment

The CMS runs as a systemd service on a Hetzner server behind Caddy. The client bundle must be built with npm run release before publishing, or the published output carries a stale SSR tree — see Deploying Umbraco.

This documentation site deploys independently to Cloudflare Workers; see Deploying the docs site.