Harper: So I was lookin' at this thing, and they're talkin' about the Sentry codebase, right? And there's this folder, 'components.' And you open it up, and there's like, two hundred files in there.
Ronan: Two hundred? Crikey.
Harper: Yeah, two hundred. And the only thing they got in common? They're components. You got 'analyticsArea' sittin' right next to 'workflowEngine.' Good luck findin' anything in that mess.
Ronan: That's exactly it. An engineer, right, they open up this ten-year-old project, and they're staring at two hundred files in a 'components' folder. From 'analyticsArea' to 'workflowEngine.' They're all just... components. No rhyme or reason to it. Just a big ol' jumble.
Harper: Yeah, and you just kinda stare at it, like, 'where do I even start?'
Ronan: Exactly! It's a proper nightmare to navigate. And the article's point is, your codebase? It's probably organised all wrong, because you're grouping things by what they are, not by what they do.
Harper: Like, I get the idea of a components folder. Makes sense, right? All your components in one spot. All your hooks in another. Your utilities in another. That's kinda how we've always done it.
Ronan: And that's the 'horizontal' split, as they call it. Components, hooks, types, utils. But what happens when 'useTheme' is living right next to 'useTodo'? They're both hooks, yeah, but they've nothing to do with each other.
Harper: Well, yeah, but they're both hooks. It's like, you know where to look if you're lookin' for a hook.
Ronan: But you don't know what that hook does or who owns it. The insight here is, the way you structure your code should mirror the way your product teams are structured. If you've got a 'billing team' that looks after the billing features, then in your code, you should have a 'billing' folder. And everything to do with billing — the components, the data fetching, the wee utility functions — it should all be in there.
Harper: So if I'm on the billing team, I go to the billing folder, and everything I need is right there? Not scattered all over the place?
Ronan: Precisely. It's like my friend, she's a chef, right? And her kitchen isn't organised with a 'knife drawer' and a 'pot shelf.' She's got a 'prep station' with all the knives and bowls she needs for prepping vegetables. And a 'sauté station' with all the pans and oils for sautéing. Everything for a specific task lives together. It's organising by workflow, not by tool type.
Harper: Oh, that's a good way to put it. So, you're not just renaming folders, you're fundamentally changin' how you think about what goes where.
Ronan: Exactly! The horizontal split is broken. That Sentry example, two hundred files in `components/`, completely unrelated. It's a disaster. And we actually solved this before, right? Remember back in the day, HTML, CSS, and JavaScript were all separate files? Then we started putting them all together in self-contained components. Because they belonged together, they changed together.
Harper: Right, like a single component has its own styles and logic, makes total sense.
Ronan: And it's the same idea here. Your code structure should mirror your team structure. If you've got a 'dashboards team' or a 'replays team,' their code should all live in one logical place. Not spread across `components/dashboards`, `hooks/dashboards`, `utils/dashboards`.
Harper: But what about, like, a really generic button component? Or a type definition that's used everywhere? Where does that go? If every team has its own folder for everything, doesn't that just create a bunch of duplicated stuff?
Ronan: Well, that's the trick, isn't it? You have to figure out the right 'vertical.' If a button's truly generic and used in a hundred places, maybe 'buttons' is its own vertical. Or it goes into a shared design system vertical. The article says finding the right vertical is the hard part, not an exact science.
Harper: Okay, that makes sense for a brand new project, right? You start with this philosophy from day one. But what about Sentry, with its two hundred components? Are you really gonna go in and refactor ten years of code into these new verticals? That sounds like a massive undertaking. Like, a huge, risky refactor that might break everything.
Ronan: Yeah, it wouldn't be easy, that's for sure. But is accepting the mess, and just relying on search tools to find things, actually better? You're just kicking the can down the road, aren't you?
Harper: But you know how those refactors go. They always take longer than you think, introduce new bugs, and then you're just trading one kind of complexity for another. Maybe the mess is a known quantity, at least.
Ronan: I dunno, Harper. A known quantity of suffering is still suffering. And this vertical approach, it's about reducing cognitive load. Making it easier for engineers to do their job, to understand the codebase. That's gotta be worth something, even if it's a big lift.
Harper: I'm not sayin' it's not valuable. I'm just sayin' the cost of getting there could be monumental for a big, old project. And then, if everything's organised by feature, what happens to the truly shared, cross-cutting stuff? You know, the things that really are used by every team, like a date utility or a global authentication hook? Do you just end up with a new 'common' or 'shared' folder that becomes the next 'utils' dumping ground?
Ronan: Well, the article hints at that. You make those common things their own vertical, right? A 'date-utils' vertical. A 'auth' vertical. But then you've just named them something else, haven't you? It's still a collection of unrelated things that just happen to be shared.
Harper: Yeah, exactly! It feels like you're just moving the problem around, not solving it. I'm Harper.
Ronan: And I'm Ronan. This has been Manish Chiniwalar's Station.