Primers

Concept-oriented overviews of how the major areas of this codebase hang together.

A primer doesn't tell you how to add a new thing (that's what the BUILDING_* how-to docs are for) and doesn't explain why one specific bit of code looks the way it does (that's tutorials). It gives you the lay of the land for an area, with links out to the deeper docs for each topic.

If you're new to the codebase, start here. If you've been here a while and someone asks "how does X work in our project", point them at the relevant primer.

What's here

  • Frontend primer — the Vite-powered public-site frontend in UmbracoCommunity.StaticAssets. Covers the dual dev workflow, the manifest-driven Razor integration, the entrypoint convention, Lit + PostCSS, testing, and what builds for production. Backoffice frontends are signposted at the end.
  • Backend primer — the C# side in UmbracoCommunity.Web and UmbracoCommunity.Web.UI. Covers the request flow (URL → render controller → view model builder → view), the three controller flavours, the builder pattern and DI registration, bootstrapping through composers, output caching policies, and the self-contained Features/Sessionize/ module pattern.
  • Multi-tenancy primer — one Umbraco instance, several sites. The single invariant (scope every content lookup to the current request's tenant), the multi-root content tree, the GetSiteSettings() / AncestorOrSelf<T>() helpers, domain-binding for routing-level lookups with no current page, and the intentional cross-tenant exceptions. Threads together the multi-tenant tutorial suite.
  • Backoffice extensions primer — the three backoffice client codebases (UmbracoCommunity.Extensions, UmbracoCommunity.BlockRestrictions, Umbraco.Community.NotFoundTracker). Covers the App_Plugins umbraco-package.json manifest, the bundle pattern, how dashboards / property editors / workspace views register and scope themselves via conditions, the @umbraco-cms/backoffice design system and UMB_AUTH_CONTEXT, calling secured C# APIs with the user's bearer token, and why each client is its own library-mode Vite project.
  • Caching primer — the dozen scattered caches mapped to the four questions they answer (deploy-time artefacts, API responses, expensive cross-request compute, slow third-party data), which mechanism each uses (RuntimeCache, static IMemoryCache, OutputCache policies, two-tier IMemoryCache, stale-fallback feeds), and what invalidates each. Includes a lookup table and "which to reach for" guidance.
  • Third-party integrations primer — the external dependencies: three server-side data feeds (Sessionize, Calendar, Community Blogs) that all follow one resilient pattern (options + named HttpClient + cache-with-stale-fallback + composer), plus the avatar/build-time bits. Notes what isn't here (Matomo, Intercom, Maps, release tracking) so readers don't go hunting.

Planned

The backlog in IDEAS.md lists primers that haven't been written yet. Each idea there also has a placeholder file in this folder with a status callout and a "what this will cover" sketch — useful if you're picking one up to write, or just want to scan what's coming without reading the backlog index.

Adding a new primer

A new primer earns its keep when an area of the codebase has:

  • More than one or two surface-level concepts a new contributor needs to hold in their head, and
  • A scattering of how-to / tutorial / reference docs that benefit from being threaded together.

If the answer fits in a paragraph in CLAUDE.md, it doesn't need a primer. If you find yourself writing the same "let me explain how X works in this project" thread three times, it does.

See IDEAS.md for candidate primers worth writing. Each one already has a stub file in this folder — expand the stub in place rather than creating a new file, then move the entry out of the backlog and into the What's here list above in the same commit.

You don't need to maintain a contributors list by hand. Each rendered doc shows a Contributors section generated from git history (docs/contributors.generated.json, produced by npm run generate:doc-contributors and refreshed in CI). Open a PR and you'll be credited automatically — with your GitHub avatar where your commit email is linked to your account.

  • Backend primer

    The C# side of the site lives across five projects, with src/UmbracoCommunity.Web/ as the heart of it all — controllers, view model builders, services, view components, and the small ASP.NET integrations Umbraco doesn't ship by default. The aim of this primer is to give you the lay of the land on the backend, as sibling to the frontend primer. Each section sketches what's there and signposts a deeper doc for when you need it.

  • Backoffice extensions primer

    The frontend primer covers the public site and deliberately punts on the backoffice — the Umbraco admin UI at /umbraco. This repo ships three separate backoffice extension codebases, and this primer threads them together: how an extension reaches the backoffice at all (the App_Plugins manifest), how individual pieces of UI register themselves, how those pieces talk to the secured C# APIs behind them, and why each one is its own little Vite project rather than part of the public-site build.

  • Caching primer

    Caching in this codebase isn't one system — it's a dozen small decisions made in different places, each reaching for whatever cache fit that problem. That's fine, but it means "how is X cached?" has no single answer until you know which kind of thing X is. This primer maps the caches to the problems they solve, so you can tell which one to reach for (and what invalidates it) without spelunking.

  • Content modelling primer

    Document types, element types, block types, and the compositions (ICompositionPageConfiguration, ICompositionSeo, ...) that share fields across them. The auto-generated PublishedModels namespace that turns all of those into typed C# classes. The view-model-builder pipeline that converts IPublishedContent into the view-shaped models the Razor templates actually render against. This primer will thread the Models/ folder structure together with the BUILDING_PAGES.md and BUILDING_BLOCKS.md how-to guides so a new contributor can hold the whole shape in their head.

  • Frontend primer

    The public site's frontend lives in src/UmbracoCommunity.StaticAssets/ — a Vite + TypeScript + Lit project whose job is to build the JS, CSS, and other static assets that the Razor views in UmbracoCommunity.Web.UI load at request time. The aim of this primer is to give you the lay of the land — each section sketches what's there and signposts a tutorial, how-to, or source file for when you want to dig in.

  • Third-party integrations primer

    The external dependencies this site talks to are, almost entirely, a handful of server-side data feeds that pull content from someone else's API — and the good news is they're all the same shape, so learn one and you can read or add any of them. (There are also a couple of avatar / build-time odds and ends, covered at the end.)

  • Multi-tenancy primer

    This site runs several distinct sites from one Umbraco instance — each site is a tenant, with its own root content node, its own domain, its own settings and content, but a shared media library, shared user accounts, and a single deployment. That arrangement is cheap and convenient, and it comes with exactly one rule you have to keep in your head for nearly everything you write. This primer gives you the five-minute orientation; the tutorial suite it links to has the depth.

  • SEO and structured data primer

    Schema.NET, the schema builders (ArticleSchemaBuilder, OrganizationSchemaBuilder, BreadcrumbSchemaBuilder), the MetaTags ViewComponent, OpenGraph and Twitter Cards in Layout.cshtml, sitemap generation, and canonical URL handling. This primer will be the orientation layer that holds the whole SEO surface in one place; the tenant-aware schema fallback tutorial is the deep dive for one specific corner of it.