Shell Architecture & Centralised SSO
Iran Fava Gostaresh · IKCO Group
- React
- TypeScript
- Shell Architecture
- SSO
- Token-based Auth
- Zustand
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 challenge
The architectural layer underneath the group’s platforms: a host shell that owns authentication, routing and shared chrome, so independent business services share one session without any of them handling credentials.
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.
What I did
- 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.
Key features
- 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.
Result
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.