Shell Architecture & Centralised SSO

Overview

Several business services — vehicle sales, digital contracts, signing, account management — needed to feel like one product to the user while staying separate products to the teams building them. The shell is the layer that makes that true: it owns the session, the navigation chrome and the routing, and it hands each service a scoped token rather than a credential.

The problem

The default outcome when several teams build "one" app is either a monolith that nobody can deploy without coordinating, or a set of separate apps that each ask the user to log in again. Neither is acceptable when the journey crosses services mid-purchase. The genuinely hard part is token handling: every service needs authenticated access, no service should be able to leak a credential, and a token refresh happening in one service must not log the user out of another.

Approach

• Centralised the session in the shell. Business services never see credentials — they receive a scoped, short-lived token and ask the shell when they need a fresh one.
• Made token refresh a single-flight operation at the shell level, so concurrent expiry across services produces one refresh rather than a stampede.
• Gave each service its own route namespace and its own deployment, with the shell resolving which service owns a URL.
• Kept shared chrome — header, navigation, session state, error boundaries — in the shell so services cannot drift visually or handle auth errors inconsistently.
• Defined the shell/service contract explicitly, so a new business service integrates against a documented interface instead of reading another service’s source.

What shipped

• One session across every business service in the group.
• Independent deployment per service — no coordinated release train.
• Single-flight token refresh shared across services.
• A documented integration contract for onboarding new services.

Outcome

Teams ship on their own schedule while the user experiences a single signed-in product. Onboarding a new business service is an integration against a known contract rather than a merge into a monolith.