Walking the Netflix Paved Road (Bumps Included): Web Framework, Hawkins Design System

Hi all, so I'm Misha. I'm a UI engineer at Netflix. So at Netflix, my team builds tools for content analysis. So to put it simply, we help detect some scary and grown up stuff in the titles. So that shows like Squid Game or Stranger Things are recommended to you, but not to your little kids. And also, these days I spend a lot of time on developer productivity, in particular trying to help increase AI adoption, of course, across Netflix teams. But I'm not going to talk a lot about AI today. Well, a bit. Instead I want to show you what it took for our product team to adopt UI platform tooling, which Netflix provides, or as we also call it, the paved road tooling. There will be two real-life examples, so two real-life challenges. And hopefully you can use the learnings that you got from the process at your own company.

So to set some context, let me tell you a bit about what Netflix UI platform is. So what's that and why do we need it? Let's imagine you'd like to watch something on Netflix. Let's say Squid Game. So please raise your hand if you have watched Squid Game. Nice. Yeah, because I have a lot of references to this show, so it's very good that almost all of you have watched it. So you go to Netflix.com, you search for the show, there it is. But before a movie is ready to play, it actually goes through a long journey. First you need a screenplay. Then you need to sign deals with actors, writers, directors, producers, etc. Then financials are handled because you need to pay money for those stuff. And then finally the movie is filmed and produced. It's promoted, it's localized, it's age-rated. By the way, that's my team. We help age-rate movies. And that's just the surface. So there are hundreds of internal apps that help to power all this process behind the scenes. Like hundreds of them. And you've also probably heard a bit about Netflix culture.

It's built kind of on top of speed. You need to iterate fast, you need to pivot, adapt fast, you need to run experiments, innovate. And also, the processes or bureaucracy should not stop you. So there is a minimum of those. But also for the business to be successful, it needs to balance those things with quality, consistency, predictability, and multi-platform support. So that every device supports it, so that you don't find bugs. I know there are some, but hopefully there is a minimum amount of those. And these two groups, they don't always match. So Netflix has come up with a solution to this mismatch, and this solution is platform tooling.

So by saying platform, I mean the shared tools and libraries, like the common ones, that help you ship applications fast without sacrificing quality. And on the web UI side, we call those tools UI-paved road. Like a road which you can drive or walk, so it's easier for you. But the spoiler alert is that there are some bumps on this road, and I will walk you through some of them. So why would you actually migrate to platform at all? Because every code base grows in complexity over time, right? But when you migrate to platform tooling, a big chunk of that complexity goes away.

Because you no longer need to support all those custom solutions that you would otherwise support if they were not provided. So after adopting platform, the complexity, maintenance effort, and onboarding drop, and at the same time, those things that I mentioned before, like reliability, also productivity, consistency and security, all they go up. Because the platform team now handles it all for you. And just to reiterate, by saying platform, I don't mean stuff like Android, iOS, or web, I just mean this combination of tools, specifically on the web UI side, that are shipped for product teams to be faster and more productive. So this is what we had before platform tooling, or before UI-PR, as we call it.

So every team picked tools that worked best for them. As you can see here, the JavaScript bundlers used across the apps include React Scripts, Vid, Webpack, Gulp. Some familiarity with CrackoCracko? Yes, we used it. The variety of tools extended beyond bundlers to styles, forms, tables, localization, and other tooling. The platform team transitioned from eight different bundlers to a single recommended road through three phases: analyze, select, and bundle.

UiPaved Road now relies on two key components: the web framework and Hawkins design system. The web framework acts as the centralized bundler for all tools provided to teams. Adoption of this framework transformed the architecture of applications, simplifying dependencies pre-UiPR. Previously, apps relied on additional custom packages like application provider for various integrations and tools.

This simplified version illustrates the transition post-UiPR. The app now depends on reusable packages like movie search and user menu. Before platform adoption, it also required an application provider for custom tools integration with internal systems and other custom packages for functionality like authentication and shared tools.

And start supporting it as a platform. And third stage is that you need to bundle those tools together so that teams can just adopt them in one click, like one click installation. Of course, it's never always one click, but that's the goal.

So these days, UiPaved Road, or UiPR, stands on two pillars, web framework and Hawkins design system. The framework is that first pillar, and that's actually that bundler of all of the different tools that are provided to the teams. Let me show you what adoption of this web framework looked for our team.

From the architectural standpoint, it's just a monorepo app that depends on two reusable packages, movie search and user menu. But it's actually not that simple because it's pre-UiPR. This simplified version illustrates the legacy setup that we inherited. Our platform team worked hard and now we have the equivalence of all of those things provided by them.

So you need a movie search component, and you need this user menu, for example. From the architectural standpoint, it's just a monorepo app that depends on two reusable packages, movie search and user menu. Looks simple, right? But it's actually not that simple because it's pre-UiPR. So it's before we adopted platform. Instead, this app and the packages depend on another package called application provider.

It's like a provider of all of those custom tools. Also another custom package that we had in our monorepo. It handled the integration with internal systems, like the authentication into network system, and provided some common share tools like configure-graphql-client, feature-flex, telemetry, and many more. Application provider pulled all those things from other custom packages that live inside our monorepo. A monorepo of 50 packages and 10 apps. All that we own, like our team owns.

On top of that there is also this community layer of some libraries for authorization, login, and more, maintained by entire Netflix enterprise community. And each application also has its own configs and code generation logic, like typescript config, vidconfig, testutils and stuff. So this is the legacy setup that we inherited. And if you look closer to this scheme, you can see that many of those things can actually be reused across multiple applications. Because most applications need things like authorization, error handling, feature-flex, telemetry, all of that on the left of the screen. Typescript and other configs can also share some defaults.

This must be provided by the platform, by the UIPR team. And it actually is. So our platform team worked hard and now we have the equivalence of all of those things provided by them. So we no longer need to maintain all those custom alternatives in our monorepo. You can see that monorepo is much leaner now. But we still have that application provider, and its role is just to pull those things and provide them to apps and packages.

But if application provider is just an orchestrator of all those platform libs, this obviously means that it should be supported by a platform as well. Every app does not need to have its own application provider. And that's exactly how the framework was born. So now our apps just need to plug into a framework entry point, and the same for our packages. And we get all of those platform tools out of the box. So no more custom infrastructure packages living in our monorepo. That's the ideal state of our monorepo.

The application just needs to handle the business logic and nothing else. So to reiterate once again, the framework gives you this enterprise-ready, pre-configured application setup out of the box, and all of that is managed by the platform team. The platform team also keeps your dependencies up to date, and it also provides a plugin system in case you still need something custom. So now hopefully you can see why the framework became the migration goal for our internal applications. But we were also one of the first teams to migrate, so we had to figure out the process first, not to be like that guy.

So our first approach, big bank migration. Replace application provider, that orchestrator, and all of the custom packages that we had in our monorepo with a framework across all apps and packages at once. Sounds great. A quick question for you. Who has tried a big bank migration like that and succeeded? Yes. You probably now understand where it's all going. Once again, the scheme of our monorepo.

The app and packages all depend on the application provider. Then you just need to swap those dependencies to a framework, right? But then there is another app, and it also pulls the same stuff. You can't have both the application provider and web framework inside one monorepo because under the hood they configure the same tools. So we have dependency conflicts. It's not that easy to resolve those. So you would need to migrate that second app as well.

But then we have more of those, right? We have 50 packages and 10 applications. So you can't migrate one of those things without migrating all of them. It's like a snowball effect. And that's the actual dependency graph of our monorepo before we adopted the platform. This thing in the center is the application provider, and many of those blocks are those custom packages. During this approach, the problems kept compounding. So the first problem is this tight coupling. Because all apps and packages depend on the same things and you can't migrate one without migrating them all.

And you also can't verify that the migration works until you complete the entire process. So that's like hell. And bugs are everywhere. It's impossible to reliably catch all the regressions until you complete the entire process and it never happens. Incompatible features, because, well, our monorepo was in a bit of a legacy state. So some libraries were outdated, so we needed to upgrade them, and once again you need to do it for the entire repo first.

Some missing features that the framework didn't cover at all, because it's a new product in our company. So yeah, we had to come up with the feedback on what needs to be added. Cross-team coordination is, like I said, because all of the teams need to deliver the migration and until they do, the process cannot be complete. And obviously each team also has its own roadmap. Frequent rebases to stay up to date with the development.

And the cherry on top, a million line diff. It wasn't like a million lines, but still a lot. So this approach failed. Obviously it had some, you know, wins. Not the wins, but the pros. For example, you only need to do it just once for the entire monorepo and it's done. Everyone benefits from what the platform provides. It's also a focused effort that you can track and put on your roadmap, into your sprint, or however you manage projects. Also it exposed all of the problems that we have. But the bottom line here is that there is no room for error with this approach. One blocker stops the entire process and teams also have to wait for each other.

And regressions are also very hard to catch and verify. And after every change, you also need to go through that entire verification process from the beginning for all of the applications. So it's not sustainable. So instead we went with this phased approach, the second approach. We split this one migration effort into three phases. Preparation phase, the migration itself, and the follow-ups. And we also pinned the dependencies per app, so that the framework and application provider and all of those custom things can coexist together. This solved this dependency conflict's hell and unblocked us to migrate apps one by one, like app by app.

So we start with one pioneer app to figure out the process and estimate the effort. Then we replicate it to the second app, then the next. And even if one application migration fails, it doesn't block the entire process. So with this approach, there is much more green. Obviously you get flexibility because you can control like the timing on when to migrate each application. You get also white gloves supported from the platform because it's easier for them to help you with migrating one application instead of your entire Monorepo. And also the pioneer application becomes the blueprint for every other app to follow.

As for the tradeoffs, some apps still lag behind because some teams start migration later. And the Monorepo is also a bit messy temporarily because since we pinned the dependencies, some apps pulled the same, sorry, pulled different versions of the same third-party libraries. So for example, npm install took like 20 minutes until we completed this entire process. But still, compared to the previous approach, that's much better. And here is this approach in practice. Yeah, probably you don't see everything that's written there, but that's exactly the point. Because now, instead of one massive effort for the migration, you have this list of small independent tasks.

The same set of steps that each team can follow. And each phase can also be done separately. And those items can be parallelized and verified on their own. And once you've documented this process, like this high-level plan, the step-by-step guides, the pull requests, you can hand that runbook to your most hard-working teammate. This one. The one that never complains about rebating.

So outcomes of this phased approach is that we went from two months for Pioneer app migration to under one week for every subsequent app. The reason is how well the process was documented and how easy it was to follow. After that, after the Pioneer migration, we turned the documentation and the artifacts like pull requests and stuff into an agent skill so that AI can run migration end-to-end for you. And the documentation and the skill also turned out useful not just for our monorepo but across the entire company.

So what we learned from that is first, divide and conquer, right? Because Big Bang failed because it was so big and monstrous, so it's better to ship one small item at a time. Fail fast, but adapt faster. Big Bang failed, but it also exposed every blocker that we had and helped shape the phased approach migration. Collaborate with the platform. We gave early feedback on those missing features. Some bugs got fixed and the framework became much better than it was at the beginning. And finally, leave a runbook like step-by-step guides, decision logs, pull requests, something that every other team can follow, like every human can follow and not just humans like we did.

Now, the second pillar, the one I mentioned, Hawkins Design System. It's our Netflix in-house build, in-house system, like built on top of Material UI. Basically that's the building blocks of your application. So this is components, forms, tables, guidelines, usage metrics, all built with performance, reliability, and consistency in mind by our platform team.

So one of the case studies or challenges that we faced with this design system is this new table component adoption. So here is one of our tables in the application. It's implemented using Hawkins Table Component, which is built on top of a third-party library, React Data Grid. Have you heard of that library? OK, now, have you heard of this one? Agigrid React. Yeah, I know. They are sponsors of this conference. By the way, we are not affiliated.

So our Hawkins team decided to use Agigrid to build the next version of the table component because it has more features and it's also faster, like performance is better. So overall it's better. They are calling that component Hawkins Table Next. And since the APIs are different for those third-party libraries, they want to duplicate the old one, so that in the future we only use Hawkins Table Next. But that's just an announcement because this component is still under development. So how do we go with it now? Because as a product team, we need to keep shipping new features, right?

So do we wait, sorry, do we use the old table and ship new features now? Or do we wait for the new component and ship features later? For the old table, there are pros and cons. No delay in product work, familiar APIs, but creating technical debt in advance for future duplication. On the other hand, the new table avoids creating technical debt but introduces a delay in product work and a learning curve with new APIs. The team decided to find a new way to handle this dilemma.

Here's how we approached it: Step 1 involved using Aggrid React APIs directly to start without waiting for the new component release. Step 2 planned for a seamless swap of components once the new table is released, leveraging similar APIs for easier migration. Step 3 focused on gradual cleanup and migration of all tables to eliminate references to the old one. This approach was termed 'forward adopt,' aiming for early feedback and proactive feature shaping before the release of the new component.

The wins of this approach include no product work delay, reduced technical debt, and the opportunity for early feature feedback. However, there are trade-offs like a learning curve, initial styling, and licensing adjustments due to direct use of a third-party library. Despite these challenges, this method was deemed superior to alternatives. Key lessons learned include the importance of aligning direction over timing, ensuring non-negotiable product work, and providing early feedback to drive improvements in the development process.

Step 2. Once it's finally released, you just need to swap one component for each other. And since the APIs are similar, it will be easier than migrating to this component from scratch. And finally, step 3. Just do the cleanup and gradually migrate all the other tables until you have no references to the old table. So yeah, we called this approach forward adopt, because I haven't found any other similar architectural pattern. And the wins here is that there is no delay in product work, you have less technical data to address later, and you also get to give early feedback on the features. So you can shape the release of the table next component before it's released.

The trade-off is that it still has the learning curve. You also need some initial styling and licensing workarounds, since you're using the third party library directly. And there is a small cleanup after the final swap. But compared to the alternatives, we found that a better approach. So what we learned from it is first, align direction and not timing. Because you can't always wait for the platform, because some product work can't wait. So instead, if you align the direction where you're moving, you meet at one point. Second, is that product work is non-negotiable. Your stakeholders should never know or never care about the migration that you're doing. This is what keeps you trusted and accountable to make such decisions in the future. And finally, give early feedback. Like I said, our feedback helped to shape the final release. So next time you're waiting for the perfect tool to drop, start with what you already have. Align early and pave the road yourself.

And by the way, we're hiring at Netflix. So if anything you saw was familiar or caused flashbacks, or if you want to work on similar challenges yourself, feel free to scan the code or find me on LinkedIn any time. Thank you. You're a great crowd.

I'll start with one from anonymous. How did you convey to leadership that this project was worth pursuing? It can be challenging to justify re-architecture and migration. Yeah, I agree that the buyout is probably the most challenging part. But I would say that it wasn't just our move to convince leadership, but it was also the decision the platform team had to pursue. Because initially, it's their team who are responsible to introduce all of those shared common tools. And it's their role to convince the leadership basically.

Fantastic. Thank you. And another question is, how did you prevent the product teams from isolating themselves into their own little island? So I love that you mentioned at the end about making sure that they never know about the implementation details of packages and migrations. But how do you try to get them to contribute to the migrating or the building of the tool? Yeah, so it's important here not to isolate your work. So since you're working in Monorepo, it's actually easier. Because all of the contributors to the Monorepo, they see the pull requests that you're creating. And it's also easier for them to start doing this stuff on your own after they have an example. And especially after we created the migration skill, it became even easier.

Because now they just need to run the skill and verify that it works after the skill is done. Awesome. Thank you. And we have time for a couple of more.

When did you guys create and adopt the platform UI framework? Is this something that is fresh? And has it matured already? If you're talking about the web framework, it's pretty fresh. I would say it's one year old. But Hawkins Design System existed for years. It just kept evolving and upgrading. And some new components appear there. OK.

Do you have any regrets, is the second part to that question? I only regret that AI didn't appear earlier in this process. But overall, we learned a lot from it. Yeah. Can I ask you to come and sit on this chair? Yeah. Sure. Sorry, guys. Sorry, people online.