Per-Tenant Theming & Configuration Architecture

Overview

Content Catalyst serves 275,000+ subscribers across many tenants, each needing their own branding and navigation without forking the codebase. I built the per-tenant configuration architecture that makes this possible: every tenant runs the exact same codebase in production, themed app-wide from a single stored config applied at request time, not baked into a separate build.

What's configurable, app-wide

Colours: primary and secondary, plus app bar and navigation bar background/button colours, and card background/border colours. Typography and fonts: a separate header font and body font per tenant, chosen from a curated font registry, driving the whole type scale from h1 down to captions and buttons. Density: three presets, Compact, Balanced, and Spacious, each with its own complete type scale, so a tenant picks one feel and it's applied consistently everywhere rather than tuned page by page. Layout and branding on top of that: header/login logo height, app bar height, card corner radius, and favicon.

This runs through MUI's CSS-variable theming: config is mapped into theme options on the server for every request, so a tenant's look updates the moment an admin publishes a change, no rebuild or redeploy.

How it stays in sync, production-side

The same pattern powers Themes, Navigation Links, Favicons, and Search Results Config, spanning four repositories: AWS provisions the versioned table and IAM permissions, AIM Admin is where a site admin authors and publishes the setting, AIM Frontend reads the published config server-side and maps it into the running app, and the legacy C#/.NET backend (IReports/CCM) gets feature-toggle-gated navigation entries wired in directly, so tenants still on that system stay covered too. The architecture is now in use by 92% of active customers.