We rebuilt the heart of our identity system — live, at scale, and without a single disruption. Here’s how we transformed a legacy monolith into a modular, high-trust authentication platform for millions.
Introduction
Bazaar’s Identity Platform is the authentication nucleus of our product ecosystem — orchestrating access for every user touchpoint, from our Grocery app and Rider interface to internal admin portals. It’s not just a login service; it governs:
- Sign-up, login, OTP verification
- Session lifecycle management
- Role-based access control
- OpenID Connect (OIDC) integration
- Multi-factor authentication
At peak, it processes 7000+ requests per minute , handling millions of sessions across guest and registered users. Its stability defines the health of the entire platform. Any change to token behavior would ripple across every consumer product and backend — making correctness, reliability, and backward compatibility non-negotiable.
⚠️ The Problem: Token Renewal at Scale Was Cracking
Historically, our identity system issued JWT access and refresh tokens to both guests and registered users. Clients relied on a shared API endpoint to refresh tokens every n minutes.
This approach began to show its cracks:
- 🚨 Guest token renewals overwhelmed the identity-service with unauthenticated traffic.
- 🧩 Token lifecycle logic became entangled with authentication and session logic.
- 🧱 Domain boundaries blurred , making the system increasingly hard to evolve.
- ⚙️ Scaling stress — over 1.9M+ active guest sessions stored and rotated in DB.
This wasn’t just a performance bottleneck — it was an architectural red flag. The system needed to evolve or it would constrain our future growth.
Inspired by Global-Scale Identity Platforms
We studied battle-tested identity systems to inform our design:
- Amazon : Session-token IDs for opaque anonymous flows
- Spotify : Isolation between guest discovery and user-authenticated APIs
- Uber : JWT enrichment at the edge via Envoy to decouple downstream auth
These insights helped define our guiding principles.
Design Goals
- Reduce guest token renewal traffic on identity-service
- Introduce stateless guest sessions to remove DB dependency
- Preserve full backward compatibility for legacy clients
- Establish clear token domains: Guest, User, and Service
- Safely deliver change using TDD, BDD, and progressive rollout
From Monolith to Modular: Restructuring Identity as a Scalable Platform
Before any token migration could succeed, we needed to modernize the very structure of our Identity Platform.
What started as a monolithic mudball — entangling session logic, token management, login flows, and user models — was reimagined into a vertically sliced architecture, with clear boundaries, modularity, and domain ownership.
🎯 Why Vertical Slicing?
- Our legacy system suffered from tight coupling between concerns — login flows touched session storage, token validation logic was scattered, and shared models leaked across contexts.
- Engineers had a hard time making localised changes without risking unrelated functionality.
- Adding support for new flows (like partner logins or stateless sessions) meant touching unrelated parts of the system.
🧩 Our Modular Design Approach
We restructured the platform into independent, domain-aligned vertical slices , such as:
- GuestService
- UserService
- SignupService
- OTPFlowHandler
- SessionLifecycleManager
Each module:
- Owned its models, rules, business logic, and persistence.
- Was exposed via explicit interfaces (REST or internal contracts).
- Was testable, deployable, and evolvable in isolation.
This modularization accelerated development, simplified testing, and reduced the blast radius of changes — giving us the foundation to implement the new token lifecycle with confidence.
🔄 Future-Ready Foundation
This shift wasn’t just about scaling what we had — it enabled:
- Easier onboarding of engineers by navigating clear module boundaries.
- A pathway to microservices, as each vertical slice could become its own service.
- Faster incident resolution due to localised ownership and observability.
🔄 Our Engineering Approach (Token Migration)
This wasn’t a feature refactor — it was a core identity infrastructure rewrite , under live, high-scale traffic. We chose to evolve the system incrementally and surgically.
🔁 1. Stateless Guest Session Tokens
Instead of persisting or rotating refresh tokens for guests:
- We issued opaque session tokens signed with a platform-wide secret
- Tokens had a long but bounded TTL
- Result: 70%+ drop in guest renewal traffic to identity-service
2. Enriched JWTs via Spring Gateway
Based on the accessLevel claim (GUEST, USER, SERVICE), we:
- Injected custom scopes and metadata into headers at the Gateway
- Allowed downstream services to stay stateless and avoid JWT parsing
3. Middleware Unification
All backend services received a uniform header structure , regardless of caller type. This centralised auth logic while keeping the gateway lean.
4. Seamless Backward Compatibility
Legacy clients still expecting guest refresh tokens (refreshToken = "GUEST") were gracefully intercepted and served valid tokens from the new guest_session API — no app updates required.
Engineering Practices That Enabled Safe Change
- TDD & BDD : Outside-in test design enabled refactoring behind robust test coverage
- Trunk-based development : Incremental PRs with clear ownership
- Ping-pong pairing : Rapid peer iteration kept velocity high without compromising safety
- Stateless-first mindset : Reduced session state complexity at scale
- accessLevel claims : Cleanly routed and enforced logic boundaries across the stack
Outcomes & Impact
Despite refactoring one of the most sensitive systems in our infrastructure, we shipped without a glitch. Here’s what we achieved:
- Zero downtime during rollout
- 70% reduction in guest traffic to identity-service
- Full backward compatibility — no client-side changes
- Simplified operations — no need to manage guest session DB entries
- Clear domain boundaries for Guest, User, and Service tokens
- Enabled partner token flows with SERVICE scoped JWTs
- Robust test suite for long-term maintainability
Final Thoughts
Rebuilding identity wasn’t about rewriting a few endpoints.
It was about evolving a monolith into a modular, testable, and scalable platform.
It was about building trust — at platform level , at engineering level , and at user level.
Top comments (0)