Applying FSD Architecture: Answering "Where Should This Code Go?" with Clear Code Location

Kakaopay's ceo-plus repo became increasingly complex as features grew, with components, apis, pages, and helpers becoming intermixed, raising the cost of deciding where code should live. As a result, exploration time increased, and inconsistency in how different engineers interpreted the structure grew alongside anxiety about side effects.

To solve this, the team introduced FSD (Feature-Sliced Design). FSD is an architecture that divides code into Layers > Slices > Segments to control reuse scope and dependencies, premised on a unidirectional structure where higher layers only reference lower layers.

The core layers are app, pages, widgets, features, entities, and shared, and in this project the team decided not to use the widgets layer. Since the proportion of independent, large-scale UI components was low, it made more sense to manage feature units mainly within features.

Also, pages was allowed to have slice grouping among slices in the same domain, reducing excessive slice creation. This was because, given the service's characteristic of having multiple pages within the same domain—like benefits and coupons—splitting a slice per page could make the structure complex again.

API locations were also redefined.

• pages/[slice]/api: APIs used only by that specific page
• features/[slice]/api: feature APIs reused within the same page group
• entities/[domain]/api: domain APIs shared in common across multiple page groups

Migration was carried out bottom-up rather than flipping everything at once. The rule was to first place code in pages, then move it to features if reused across multiple pages, to entities if reused more broadly, and to shared for global common code—allowing the team to naturally build a sense of the layers.

After applying this, the role of code could be immediately understood just by looking at its location. As reuse scope became clear, incorrect dependencies were reduced, and cohesion at the feature-unit level increased, making refactoring and testing easier. Ultimately, FSD worked as a practical structural solution that clearly defines where code should belong.