Frequently Asked Questions About Dima's 5-Rule Front-End Architecture Evaluator
21 answers covering everything from basics to advanced usage.
// Basics
What is high cohesion in front-end architecture?
High cohesion means all code related to one business feature is concentrated in one place. You measure it by counting how many files you need to open to change one feature and how close those files are to each other. If changing a button's behavior requires edits in five different folders, cohesion is low. High cohesion reduces context-switching and makes features easier to maintain.
What is the difference between slice-level cohesion and feature-level cohesion?
Slice-level cohesion means code within a single FSD slice is well-organized internally — its UI, model, and API segments are tidy. Feature-level cohesion means all code for one complete business feature across all technical concerns lives close together. FSD achieves good slice-level cohesion but has low feature-level cohesion because one feature's code is scattered across multiple layers (features, entities, widgets).
What is incremental adoption in architecture and why does it matter?
Incremental adoption means you can start a project with a simple structure — just two or three folders — and add architectural rules only as pain points emerge. It matters because early-stage projects have unstable requirements, and committing to full structure upfront (like FSD's seven layers) wastes effort if the project pivots or doesn't survive. Architecture should grow with proven need, not prediction.
// How To
How do I test for the Classification Problem on my team?
Ask two or more developers independently where they would place a specific component — for example, a shared search bar or an add-to-cart button. If they disagree on which layer it belongs to (widget vs. feature vs. entity in FSD), you have a Classification Problem. This test reveals whether your architecture's categories are ambiguous, which directly harms discoverability and causes inconsistent file placement.
How do I score an architecture on the Cohesion-Coupling matrix?
First assess cohesion: does changing one feature require touching many scattered folders (low) or just one area (high)? Then assess coupling: does changing one module break other modules unexpectedly (high coupling) or not (low)? Plot the intersection. Bottom-right (high cohesion, low coupling) is ideal. Top-right is a God Object. Bottom-left is Destructive Decoupling. Top-left is Poorly Chosen Boundaries.
How do I migrate from Feature Sliced Design to Vertical Slices?
Migrate incrementally by collapsing layers into feature folders. For each business domain (e.g., cart), create one feature folder and move its related code from the FSD features, entities, and widgets layers into sub-folders (UI, logic, API) inside that feature folder. Start with the most painful feature — the one causing the most merge conflicts or confusion — and migrate one domain at a time while keeping the rest in FSD.
How do I set up a Layered Architecture for a small front-end project?
Create five top-level folders: components (reusable UI), services (business logic), api (data fetching), pages (route-level components), and shared (utilities, constants, types). This gives you clear separation of concerns with minimal overhead. As the project grows beyond five to eight features or three to four developers, watch for signs you need to migrate to Vertical Slices — merge conflicts, unclear file placement, or features scattered across all three layers.
// Troubleshooting
My shared folder keeps growing — what's going wrong?
The shared folder is becoming a dumping ground, which is one of the most common pitfalls. Shared should contain only truly reusable, business-logic-free utilities — design tokens, generic UI components, HTTP clients. If you find business-specific code there (like an add-to-cart component), it belongs in a feature folder or slice. Audit shared regularly: anything with domain-specific naming should be relocated to the feature or slice it serves.
Developers on my team keep putting files in different folders — how do I fix this?
This is the Classification Problem, and it signals ambiguous architectural boundaries. First, confirm it by having developers independently classify the same component. If they disagree, your layer definitions are too vague. Fix it by either simplifying your architecture (fewer layers means fewer ambiguous placements) or by creating explicit, written placement rules with real examples. Vertical Slices reduce this problem because the primary division is by business feature, which is less ambiguous than technical categories.
We adopted FSD but our project is small — should we keep it?
Probably not. FSD requires the full structure from day one — all seven layers, naming conventions, and import rules — which scores poorly on Incremental Adoption for small projects. If your team is struggling with placement decisions or the overhead feels disproportionate to the project size, migrate to a simpler Layered Architecture or Vertical Slices. Collapse FSD layers into feature folders incrementally, starting with the most problematic areas.
What are the signs that my front-end project needs more architecture?
Key signals include frequent merge conflicts on the same files, developers unable to find code without asking teammates (low discoverability), new hires taking weeks to understand the codebase, unexpected side effects from seemingly isolated changes (high coupling), and disagreements about where new code should go (Classification Problem). These are feedback signals in the Architecture Decision Loop that indicate you need more structure — typically a migration from Layered Architecture to Vertical Slices.
What are the signs that my front-end project has too much architecture?
Signs include: creating empty folders just to satisfy the architectural pattern, spending more time debating component placement than building features, having layers with only one or two files each, and developers feeling slowed down by import rules on a small codebase. If your project has fewer than five features or fewer than three developers, a full architecture like FSD is likely over-engineering. Simplify to Layered Architecture and add structure only when pain emerges.
// Comparisons
How does the 5-Rule evaluator compare to just using common sense when picking an architecture?
Common sense often leads to gut-feel decisions biased by whatever architecture the team used last. The 5-Rule evaluator provides five explicit, testable criteria that force you to consider trade-offs systematically. It catches problems like the Classification Problem, low feature-level cohesion, or poor incremental adoption that intuition often misses. The Cohesion-Coupling matrix gives you a visual diagnostic that common sense cannot replicate.
How does Feature Sliced Design compare to Vertical Slices architecture?
FSD organizes by technical layer first (app, pages, widgets, features, entities, shared) with business slices inside each layer. Vertical Slices organizes by business feature first (cart, checkout, user) with technical sub-folders inside each. FSD achieves good slice-level cohesion but low feature-level cohesion. Vertical Slices achieves high feature-level cohesion and better Mental Model Match. FSD requires full structure upfront; Vertical Slices supports incremental adoption.
How does Vertical Slices compare to Layered Architecture for front-end projects?
Layered Architecture (components, services, API) is simpler and ideal for small projects with few features. Vertical Slices (feature-first folders with technical sub-folders) scales better for medium to large projects because it keeps all code for one business feature together, improving cohesion and reducing merge conflicts. Start with Layered Architecture and migrate to Vertical Slices when you notice features scattering across layers and developers stepping on each other's toes.
// Advanced
What is the @x notation in Feature Sliced Design?
The @x notation is an official FSD workaround for cross-slice dependencies. When one slice needs to import from another — which FSD's rules normally forbid — the source slice creates a special @x folder that re-exports the needed code. This makes the cross-import visible and explicit in the file structure. However, it does not eliminate the coupling — it only makes it transparent. Cross-slice coupling still increases architectural fragility even when declared via @x.
What is the Architecture Decision Loop?
The Architecture Decision Loop is the ongoing cycle of building, receiving feedback from the system (merge conflicts, unexpected side effects, onboarding difficulty), deciding whether to add or reduce structure, and updating the architecture accordingly. Architecture is never a one-time decision. After each release cycle, assess whether the current structure is causing pain or working well, and adjust. This prevents both premature over-architecture and structural neglect.
Can I use the 5-Rule evaluator for back-end architecture too?
The five principles — cohesion, coupling, discoverability, mental model match, and incremental adoption — are universal software design principles that apply to any architecture. However, the specific heuristics (Layered vs. Vertical Slices vs. FSD), the Cohesion-Coupling matrix quadrant descriptions, and the project-size recommendations are calibrated for front-end projects. You could adapt the scoring framework for back-end work but would need different architectural candidates and size thresholds.
How often should I re-evaluate my front-end architecture?
Re-evaluate after each significant product change — a major feature launch, a team size change, or when pain points emerge (frequent merge conflicts, slow onboarding, unclear file placement). The Architecture Decision Loop suggests treating architecture as a living decision, not a one-time choice. For active projects, a lightweight check every quarter or every two to three sprints is practical. A full five-rule audit is warranted when the team hits a clear inflection point.
What happens if I duplicate components per slice to avoid cross-imports?
You avoid coupling but introduce a DRY violation risk. If the duplicated component needs a change — like adding a loading state — you must update every copy manually. This is manageable for small, stable components but becomes a maintenance burden for complex or frequently changing ones. The trade-off is explicit: duplication reduces coupling at the cost of update consistency. Use the shared folder for truly stable, reusable components instead.
Is Feature Sliced Design worth learning in 2025?
FSD is worth understanding because it formalizes important concepts like slices, segments, and public APIs. However, the 5-Rule evaluator reveals that FSD scores poorly on Incremental Adoption and feature-level cohesion, and it introduces the Classification Problem. Learn FSD's concepts — they make you a better architect — but default to Vertical Slices for most projects unless your team is already fluent in FSD and the project is confirmed large and long-lived.